Identity Management Service API Documentation

Introduction

The Identity Management Service API provides a comprehensive set of endpoints for managing users, roles, and permissions within your organization's identity ecosystem. This API allows for programmatic control over user lifecycle, role assignments, and access policies.

Base URL: https://api.msdn.com/v1/identity

Authentication

All requests to the Identity Management Service API must be authenticated. We support OAuth 2.0 Bearer tokens. Include your access token in the Authorization header:

Authorization: Bearer YOUR_ACCESS_TOKEN

Obtain your access token through the Microsoft Identity Platform or your designated authentication provider.

Get Users

Retrieves a list of all users within the identity management system. Supports filtering and pagination.

GET /users

Query Parameters

Name	Type	Description	Required
`limit`	integer	Maximum number of users to return. Defaults to 50.	No
`offset`	integer	Number of users to skip before returning results. Defaults to 0.	No
`status`	string	Filter users by their status (e.g., 'active', 'inactive', 'pending').	No

Example Request

                GET /v1/identity/users?limit=10&status=active
                Host: api.msdn.com
                Authorization: Bearer YOUR_ACCESS_TOKEN
            

Example Response (200 OK)

{
  "data": [
    {
      "id": "usr_abc123",
      "username": "john.doe@example.com",
      "firstName": "John",
      "lastName": "Doe",
      "email": "john.doe@example.com",
      "status": "active",
      "createdAt": "2023-10-26T10:00:00Z",
      "updatedAt": "2023-10-26T11:30:00Z"
    },
    {
      "id": "usr_xyz789",
      "username": "jane.smith@example.com",
      "firstName": "Jane",
      "lastName": "Smith",
      "email": "jane.smith@example.com",
      "status": "active",
      "createdAt": "2023-10-25T09:15:00Z",
      "updatedAt": "2023-10-25T09:15:00Z"
    }
  ],
  "pagination": {
    "total": 150,
    "limit": 10,
    "offset": 0
  }
}

Create User

Creates a new user account in the identity management system.

POST /users

Request Body

Name	Type	Description	Required
`username`	string	The unique username for the new user.	Yes
`password`	string	The initial password for the user.	Yes
`firstName`	string	The first name of the user.	Yes
`lastName`	string	The last name of the user.	Yes
`email`	string	The primary email address of the user.	Yes
`status`	string	Initial status of the user (e.g., 'active', 'pending'). Defaults to 'pending'.	No

Example Request

                POST /v1/identity/users
                Host: api.msdn.com
                Authorization: Bearer YOUR_ACCESS_TOKEN
                Content-Type: application/json

                {
                  "username": "alice.wonderland@example.com",
                  "password": "SecurePassword123!",
                  "firstName": "Alice",
                  "lastName": "Wonderland",
                  "email": "alice.wonderland@example.com",
                  "status": "active"
                }
            

Example Response (201 Created)

{
  "id": "usr_def456",
  "username": "alice.wonderland@example.com",
  "firstName": "Alice",
  "lastName": "Wonderland",
  "email": "alice.wonderland@example.com",
  "status": "active",
  "createdAt": "2023-10-27T08:00:00Z",
  "updatedAt": "2023-10-27T08:00:00Z"
}

Get User by ID

Retrieves detailed information about a specific user using their unique ID.

GET /users/{userId}

Path Parameters

Name	Type	Description	Required
`userId`	string	The unique identifier of the user.	Yes

Example Request

                GET /v1/identity/users/usr_abc123
                Host: api.msdn.com
                Authorization: Bearer YOUR_ACCESS_TOKEN
            

Example Response (200 OK)

{
  "id": "usr_abc123",
  "username": "john.doe@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@example.com",
  "status": "active",
  "createdAt": "2023-10-26T10:00:00Z",
  "updatedAt": "2023-10-26T11:30:00Z",
  "roles": ["role_admin", "role_developer"]
}

Example Response (404 Not Found)

{
  "error": "User not found",
  "message": "The user with ID 'usr_nonexistent' could not be found."
}

Update User

Updates the details of an existing user. Only fields provided in the request body will be updated.

PUT /users/{userId}

Path Parameters

Name	Type	Description	Required
`userId`	string	The unique identifier of the user to update.	Yes

Request Body

Name	Type	Description	Required
`firstName`	string	The updated first name of the user.	No
`lastName`	string	The updated last name of the user.	No
`email`	string	The updated primary email address of the user.	No
`status`	string	The updated status of the user (e.g., 'active', 'inactive').	No

Example Request

                PUT /v1/identity/users/usr_abc123
                Host: api.msdn.com
                Authorization: Bearer YOUR_ACCESS_TOKEN
                Content-Type: application/json

                {
                  "lastName": "Doe-Smith",
                  "status": "inactive"
                }
            

Example Response (200 OK)

{
  "id": "usr_abc123",
  "username": "john.doe@example.com",
  "firstName": "John",
  "lastName": "Doe-Smith",
  "email": "john.doe@example.com",
  "status": "inactive",
  "createdAt": "2023-10-26T10:00:00Z",
  "updatedAt": "2023-10-27T09:00:00Z",
  "roles": ["role_developer"]
}

Delete User

Deletes a user account from the identity management system. This is a permanent action.

DELETE /users/{userId}

Path Parameters

Name	Type	Description	Required
`userId`	string	The unique identifier of the user to delete.	Yes

Example Request

                DELETE /v1/identity/users/usr_xyz789
                Host: api.msdn.com
                Authorization: Bearer YOUR_ACCESS_TOKEN
            

Example Response (204 No Content)

(No content returned for successful deletion)

Example Response (404 Not Found)

{
  "error": "User not found",
  "message": "The user with ID 'usr_nonexistent' could not be found."
}

Get Roles

Retrieves a list of all available roles within the system.

GET /roles

Example Request

                GET /v1/identity/roles
                Host: api.msdn.com
                Authorization: Bearer YOUR_ACCESS_TOKEN
            

Example Response (200 OK)

{
  "data": [
    {
      "id": "role_admin",
      "name": "Administrator",
      "description": "Full access to all system resources."
    },
    {
      "id": "role_developer",
      "name": "Developer",
      "description": "Can access development tools and APIs."
    },
    {
      "id": "role_user",
      "name": "Standard User",
      "description": "Basic access to user-level features."
    }
  ]
}

Assign Role to User

Assigns a specific role to a user.

POST /users/{userId}/roles

Path Parameters

Name	Type	Description	Required
`userId`	string	The unique identifier of the user.	Yes

Request Body

Name	Type	Description	Required
`roleId`	string	The ID of the role to assign.	Yes

Example Request

                POST /v1/identity/users/usr_abc123/roles
                Host: api.msdn.com
                Authorization: Bearer YOUR_ACCESS_TOKEN
                Content-Type: application/json

                {
                  "roleId": "role_admin"
                }
            

Example Response (200 OK)

{
  "message": "Role 'role_admin' successfully assigned to user 'usr_abc123'."
}

Example Response (400 Bad Request)

{
  "error": "Role assignment failed",
  "message": "User 'usr_abc123' already has role 'role_admin'."
}

Remove Role from User

Removes a specific role from a user.

DELETE /users/{userId}/roles/{roleId}

Path Parameters

Name	Type	Description	Required
`userId`	string	The unique identifier of the user.	Yes
`roleId`	string	The ID of the role to remove.	Yes

Example Request

                DELETE /v1/identity/users/usr_abc123/roles/role_developer
                Host: api.msdn.com
                Authorization: Bearer YOUR_ACCESS_TOKEN
            

Example Response (200 OK)

{
  "message": "Role 'role_developer' successfully removed from user 'usr_abc123'."
}

Example Response (400 Bad Request)

{
  "error": "Role removal failed",
  "message": "User 'usr_abc123' does not have role 'role_developer'."
}

MSDN API Docs

Identity Management Service API

Introduction

Authentication

Get Users

Query Parameters

Example Request

Example Response (200 OK)

Create User

Request Body

Example Request

Example Response (201 Created)

Get User by ID

Path Parameters

Example Request

Example Response (200 OK)

Example Response (404 Not Found)

Update User

Path Parameters

Request Body

Example Request

Example Response (200 OK)

Delete User

Path Parameters

Example Request

Example Response (204 No Content)

Example Response (404 Not Found)

Get Roles

Example Request

Example Response (200 OK)

Assign Role to User

Path Parameters

Request Body

Example Request

Example Response (200 OK)

Example Response (400 Bad Request)

Remove Role from User

Path Parameters

Example Request

Example Response (200 OK)

Example Response (400 Bad Request)