Absolute IdP API Documentation

Authentication: All API endpoints require JWS (JSON Web Signature) authentication. The JWS token should be provided either as a query parameter (?jws=...) for GET/DELETE requests or in the request body for POST/PUT/PATCH requests.

User Management APIs

GET /v2.0/users

Retrieve a list of users based on filter criteria passed in the JWS token.

Response Codes:

200 OK 400 Bad Request 401 Unauthorized 500 Internal Server Error

Example Request:

GET /v2.0/users?jws=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Example Response (200 OK):

[
  {
    "userUid": "550e8400-e29b-41d4-a716-446655440000",
    "username": "[email protected]",
    "firstName": "John",
    "lastName": "Doe",
    "email": "[email protected]",
    "active": true
  }
]

Error Message Keys:

Status Code	Message Key	Description
400	`idp.user.invalid`	Invalid user filter format
401	`idp.jws.invalid`	Invalid or missing JWS token
500	`idp.user.canNotProcessRequest`	Internal server error

POST /v2.0/users

Create a new user. User details should be included in the JWS payload. If userUid is not provided, one will be generated automatically.

Response Codes:

200 OK 400 Bad Request 409 Conflict 500 Internal Server Error

Example Request:

POST /v2.0/users
Content-Type: application/json

{
  "jws": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

JWS Payload Example (decoded):

{
  "iss": "your-client-app",
  "sub": "admin-user-uid",
  "aud": "absolute-idp",
  "region": "us-east-1",
  "obj": {
    "email": "[email protected]",
    "firstName": "John",
    "lastName": "Doe",
    "locale": "en-US",
    "status": "ACTIVE"
  }
}

Example Response (200 OK):

{
  "userUid": "550e8400-e29b-41d4-a716-446655440000"
}

Error Message Keys:

Status Code	Message Key	Description
400	`idp.user.invalid`	Invalid user data format
400	`idp.user.email.empty`	Email is required
400	`idp.user.email.invalid`	Email format is invalid
400	`idp.user.firstName.empty`	First name is required
400	`idp.user.lastName.empty`	Last name is required
401	`idp.jws.invalid`	Invalid JWS token
403	`idp.user.insufficientPermission`	Insufficient permissions
409	`idp.user.alreadyExist`	User already exists
500	`idp.user.canNotProcessRequest`	Internal server error

GET /v2.0/users/{userUid}

Retrieve a specific user by their unique identifier (userUid).

Response Codes:

200 OK 400 Bad Request 401 Unauthorized 403 Forbidden 404 Not Found 500 Internal Server Error

Example Request:

GET /v2.0/users/550e8400-e29b-41d4-a716-446655440000?jws=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Example Response (200 OK):

{
  "userUid": "550e8400-e29b-41d4-a716-446655440000",
  "username": "[email protected]",
  "firstName": "John",
  "lastName": "Doe",
  "email": "[email protected]",
  "locale": "en-US",
  "status": "ACTIVE",
  "active": true,
  "createdUtc": "2026-05-10T10:30:00Z"
}

Error Message Keys:

Status Code	Message Key	Description
400	`idp.user.userUid.invalid`	Invalid userUid format
401	`idp.jws.invalid`	Invalid JWS token
404	`idp.user.notFound`	User not found
500	`idp.user.canNotProcessRequest`	Internal server error

PATCH /v2.0/users/{userUid}

Partially update an existing user. Only the fields included in the JWS payload will be updated.

Response Codes:

204 No Content 400 Bad Request 401 Unauthorized 403 Forbidden 404 Not Found 500 Internal Server Error

Example Request:

PATCH /v2.0/users/550e8400-e29b-41d4-a716-446655440000
Content-Type: application/json

{
  "jws": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

JWS Payload Example (only updating firstName and lastName):

{
  "iss": "your-client-app",
  "sub": "admin-user-uid",
  "obj": {
    "firstName": "Jonathan",
    "lastName": "Smith"
  }
}

Example Response: 204 No Content (empty body)

Error Message Keys:

Status Code	Message Key	Description
400	`idp.user.invalid`	Invalid user data
401	`idp.jws.invalid`	Invalid JWS token
403	`idp.user.insufficientPermission`	Insufficient permissions
404	`idp.user.notFound`	User not found
500	`idp.user.canNotProcessRequest`	Internal server error

PUT /v2.0/users/{userUid}

Replace an existing user completely. All user fields must be provided in the JWS payload.

Response Codes:

204 No Content 400 Bad Request 401 Unauthorized 403 Forbidden 404 Not Found 500 Internal Server Error

Example Request:

PUT /v2.0/users/550e8400-e29b-41d4-a716-446655440000
Content-Type: application/json

{
  "jws": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

JWS Payload Example (all fields required):

{
  "iss": "your-client-app",
  "sub": "admin-user-uid",
  "obj": {
    "email": "[email protected]",
    "firstName": "Jonathan",
    "lastName": "Smith",
    "locale": "en-US",
    "status": "ACTIVE"
  }
}

Example Response: 204 No Content (empty body)

Error Message Keys:

Status Code	Message Key	Description
400	`idp.user.invalid`	Invalid or incomplete user data
401	`idp.jws.invalid`	Invalid JWS token
403	`idp.user.insufficientPermission`	Insufficient permissions
404	`idp.user.notFound`	User not found
500	`idp.user.canNotProcessRequest`	Internal server error

DELETE /v2.0/users/{userUid}

Delete a user by their unique identifier (userUid).

Response Codes:

204 No Content 400 Bad Request 401 Unauthorized 403 Forbidden 404 Not Found 500 Internal Server Error

Example Request:

DELETE /v2.0/users/550e8400-e29b-41d4-a716-446655440000?jws=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Example Response: 204 No Content (empty body)

Error Message Keys:

Status Code	Message Key	Description
401	`idp.jws.invalid`	Invalid JWS token
404	`idp.user.notFound`	User not found
500	`idp.user.canNotProcessRequest`	Internal server error

POST /v2.0/users/{userUid}/send-email

Send an email to a specific user. The email type and userUid should be included in the JWS payload.

Response Codes:

204 No Content 400 Bad Request 401 Unauthorized 403 Forbidden 500 Internal Server Error

Example Request:

POST /v2.0/users/550e8400-e29b-41d4-a716-446655440000/send-email
Content-Type: application/json

{
  "jws": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

JWS Payload Example:

{
  "iss": "your-client-app",
  "sub": "admin-user-uid",
  "obj": {
    "userUid": "550e8400-e29b-41d4-a716-446655440000",
    "type": "WELCOME"
  }
}

Example Response: 204 No Content (empty body)

Error Message Keys:

Status Code	Message Key	Description
400	`idp.user.sendEmail.userUidMismatch`	UserUid in path does not match body
400	`idp.user.sendEmail.invalidType`	Invalid email type
401	`idp.jws.invalid`	Invalid JWS token
404	`idp.user.notFound`	User not found
500	`idp.user.sendEmail.processingError`	Internal server error

Multi-Factor Authentication (MFA) APIs

GET /v2.0/users/me/mfa/totp/generate

Generate a new TOTP (Time-based One-Time Password) secret for the authenticated user. Returns a secret key and QR code for authenticator app setup.

Response Codes:

200 OK 400 Bad Request 401 Unauthorized 403 Forbidden 404 Not Found 500 Internal Server Error

Example Request:

GET /v2.0/users/me/mfa/totp/generate?jws=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Note:

The user identity is extracted from the "sub" claim in the JWS token.

Example Response (200 OK):

{
  "secret": "JBSWY3DPEHPK3PXP",
  "qrCodeUrl": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...",
  "totpUri": "otpauth://totp/AbsoluteIdP:[email protected]?secret=JBSWY3DPEHPK3PXP&issuer=AbsoluteIdP"
}

Error Message Keys:

Status Code	Message Key	Description
400	`idp.user.mfa.totp.generate.invalidRequest`	Invalid request format
401	`idp.user.mfa.totp.generate.unauthorized`	Unauthorized access
403	`idp.user.mfa.totp.generate.forbidden`	Forbidden operation
404	`idp.user.mfa.totp.generate.userNotFound`	User not found
500	`idp.user.mfa.totp.generate.internalError`	Internal server error

POST /v2.0/users/me/mfa/totp/register

Register a TOTP credential for the authenticated user. The TOTP registration details (secret and verification code) should be in the JWS payload.

Response Codes:

201 Created 400 Bad Request 401 Unauthorized 403 Forbidden 404 Not Found 500 Internal Server Error

Example Request:

POST /v2.0/users/me/mfa/totp/register
Content-Type: application/json

{
  "jws": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

JWS Payload Example:

{
  "iss": "your-client-app",
  "sub": "550e8400-e29b-41d4-a716-446655440000",
  "obj": {
    "secret": "JBSWY3DPEHPK3PXP",
    "verificationCode": "123456"
  }
}

Example Response: 201 Created (empty body)

Error Message Keys:

Status Code	Message Key	Description
400	`idp.user.mfa.totp.register.invalidRequest`	Invalid request or verification code
401	`idp.user.mfa.totp.register.unauthorized`	Unauthorized access
403	`idp.user.mfa.totp.register.forbidden`	Forbidden operation
404	`idp.user.mfa.totp.register.userNotFound`	User not found
500	`idp.user.mfa.totp.register.internalError`	Internal server error

POST /v2.0/users/me/mfa/totp/verify

Verify a TOTP code for the authenticated user. The verification code should be included in the JWS payload.

Response Codes:

200 OK 400 Bad Request 401 Unauthorized 403 Forbidden 404 Not Found 500 Internal Server Error

Example Request:

POST /v2.0/users/me/mfa/totp/verify
Content-Type: application/json

{
  "jws": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

JWS Payload Example:

{
  "iss": "your-client-app",
  "sub": "550e8400-e29b-41d4-a716-446655440000",
  "obj": {
    "code": "123456"
  }
}

Example Response: 200 OK (empty body)

Error Message Keys:

Status Code	Message Key	Description
400	`idp.user.mfa.totp.verify.invalidRequest`	Invalid or incorrect verification code
401	`idp.user.mfa.totp.verify.unauthorized`	Unauthorized access
403	`idp.user.mfa.totp.verify.forbidden`	Forbidden operation
404	`idp.user.mfa.totp.verify.userNotFound`	User not found
500	`idp.user.mfa.totp.verify.internalError`	Internal server error

DELETE /v2.0/users/me/mfa/totp

Remove the TOTP credential for the authenticated user, disabling TOTP-based MFA.

Response Codes:

204 No Content 400 Bad Request 401 Unauthorized 403 Forbidden 404 Not Found 500 Internal Server Error

Example Request:

DELETE /v2.0/users/me/mfa/totp?jws=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Example Response: 204 No Content (empty body)

Error Message Keys:

Status Code	Message Key	Description
400	`idp.user.mfa.totp.delete.invalidRequest`	Invalid request
400	`idp.user.mfa.totp.delete.noCredential`	No TOTP credential exists
401	`idp.user.mfa.totp.delete.unauthorized`	Unauthorized access
403	`idp.user.mfa.totp.delete.forbidden`	Forbidden operation
404	`idp.user.mfa.totp.delete.userNotFound`	User not found
500	`idp.user.mfa.totp.delete.internalError`	Internal server error

POST /v2.0/users/mfa/bulk

Perform bulk MFA operations on multiple users. The bulk request details should be in the JWS payload. Supports enable/disable operations for multiple users.

Response Codes:

200 OK - All operations succeeded or all failed 207 Multi-Status - Some operations succeeded, some failed 400 Bad Request 401 Unauthorized 403 Forbidden 404 Not Found 500 Internal Server Error

Example Request:

POST /v2.0/users/mfa/bulk
Content-Type: application/json

{
  "jws": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

JWS Payload Example:

{
  "iss": "your-client-app",
  "sub": "admin-user-uid",
  "obj": {
    "operations": [
      {
        "userUid": "550e8400-e29b-41d4-a716-446655440000",
        "action": "ENABLE"
      },
      {
        "userUid": "660e9511-f30c-52e5-b827-557766551111",
        "action": "DISABLE"
      }
    ]
  }
}

Example Response (200 OK - All Success):

{
  "status": "SUCCESS",
  "results": [
    {
      "userUid": "550e8400-e29b-41d4-a716-446655440000",
      "success": true
    },
    {
      "userUid": "660e9511-f30c-52e5-b827-557766551111",
      "success": true
    }
  ]
}

Example Response (207 Multi-Status - Partial):

{
  "status": "PARTIAL_FAILURE",
  "results": [
    {
      "userUid": "550e8400-e29b-41d4-a716-446655440000",
      "success": true
    },
    {
      "userUid": "660e9511-f30c-52e5-b827-557766551111",
      "success": false,
      "errorMessage": "idp.user.notFound"
    }
  ]
}

Error Message Keys:

Status Code	Message Key	Description
400	`idp.user.mfa.totp.bulk.invalidRequest`	Invalid bulk request format
401	`idp.user.mfa.totp.bulk.unauthorized`	Unauthorized access
403	`idp.user.mfa.totp.bulk.forbidden`	Forbidden operation
404	`idp.user.mfa.totp.bulk.notFound`	Resource not found
500	`idp.user.mfa.totp.bulk.internalError`	Internal server error