API endpoints

Every route of the REST API, with the parameters it takes and the fields it answers with. The page comes from the backend's spec at every docs build, so it lists what the code serves.

Send an API key in the X-API-KEY header with each call. REST API covers creating keys and the shape of errors. The raw spec is available as swagger.json and swagger.yaml for Postman, code generators and AI assistants.

Users

Users, their passkeys and profile pictures, login codes and signup tokens.

• post/api/one-time-access-emailRequest one-time access email
• post/api/one-time-access-token/{token}Exchange one-time access token
• post/api/signupSign up
• get/api/signup-tokensList signup tokens
• post/api/signup-tokensCreate signup token
• delete/api/signup-tokens/{id}Delete signup token
• post/api/signup/setupSign up initial admin user
• get/api/usersList users
• post/api/usersCreate user
• get/api/users/meGet current user
• put/api/users/meUpdate current user
• put/api/users/me/profile-pictureUpdate current user's profile picture
• delete/api/users/me/profile-pictureReset current user's profile picture
• post/api/users/me/send-email-verificationSend email verification
• post/api/users/me/verify-emailVerify email
• get/api/users/{id}Get user by ID
• put/api/users/{id}Update user
• delete/api/users/{id}Delete user
• get/api/users/{id}/groupsGet user groups
• post/api/users/{id}/one-time-access-emailRequest one-time access email (admin)
• post/api/users/{id}/one-time-access-tokenCreate one-time access token for user (admin)
• put/api/users/{id}/profile-pictureUpdate user profile picture
• delete/api/users/{id}/profile-pictureReset user profile picture
• get/api/users/{id}/profile-picture.pngGet user profile picture
• put/api/users/{id}/user-groupsUpdate user groups
• get/api/users/{id}/webauthn-credentialsList user passkeys
• delete/api/users/{id}/webauthn-credentials/{credentialId}Delete user passkey

Request one-time access email

post/api/one-time-access-email

Request a one-time access email for unauthenticated users

Body application/json

• emailstringrequired
• redirectPathstring

Response

204 No Content

Exchange one-time access token

post/api/one-time-access-token/{token}

Exchange a one-time access token for a session token

Path parameters

• tokenstringrequired

  One-time access token

Response

200 OKapplication/json

13 fields

• customClaimsarray of objects
  2 fields per item

  • keystring
  • valuestring
• disabledboolean
• displayNamestring
• emailstring
• emailVerifiedboolean
• firstNamestring
• idstring
• isAdminboolean
• lastNamestring
• ldapIdstring
• localestring
• userGroupsarray of objects
  7 fields per item

  • createdAtstring
  • customClaimsarray of objects
    2 fields per item

    • keystring
    • valuestring
  • friendlyNamestring
  • idstring
  • ldapIdstring
  • namestring
  • userCountinteger
• usernamestring

Sign up

post/api/signup

Create a new user account

Body application/json

• usernamestringrequired

  1 to 50 characters

• emailstring
• firstNamestring

  at most 50 characters

• lastNamestring

  at most 50 characters

• tokenstring

Response

201 Createdapplication/json

13 fields

• customClaimsarray of objects
  2 fields per item

  • keystring
  • valuestring
• disabledboolean
• displayNamestring
• emailstring
• emailVerifiedboolean
• firstNamestring
• idstring
• isAdminboolean
• lastNamestring
• ldapIdstring
• localestring
• userGroupsarray of objects
  7 fields per item

  • createdAtstring
  • customClaimsarray of objects
    2 fields per item

    • keystring
    • valuestring
  • friendlyNamestring
  • idstring
  • ldapIdstring
  • namestring
  • userCountinteger
• usernamestring

List signup tokens

get/api/signup-tokens

Get a paginated list of signup tokens

Query parameters

• pagination[page]integer

  Page number for pagination

  defaults to 1

• pagination[limit]integer

  Number of items per page

  defaults to 20

• sort[column]string

  Column to sort by

• sort[direction]string

  Sort direction (asc or desc)

  defaults to asc

Response

200 OKapplication/json

2 fields

• dataarray of objects
  7 fields per item

  • createdAtstring
  • expiresAtstring
  • idstring
  • tokenstring
  • usageCountinteger
  • usageLimitinteger
  • userGroupsarray of objects
    7 fields per item

    • createdAtstring
    • customClaimsarray of objects
      2 fields per item

      • keystring
      • valuestring
    • friendlyNamestring
    • idstring
    • ldapIdstring
    • namestring
    • userCountinteger
• paginationobject
  4 fields

  • currentPageinteger
  • itemsPerPageinteger
  • totalItemsinteger
  • totalPagesinteger

Create signup token

post/api/signup-tokens

Create a new signup token that allows user registration

Body application/json

• ttlobjectrequired
• usageLimitintegerrequired

  1 to 100

• userGroupIdsarray of strings

Response

201 Createdapplication/json

7 fields

• createdAtstring
• expiresAtstring
• idstring
• tokenstring
• usageCountinteger
• usageLimitinteger
• userGroupsarray of objects
  7 fields per item

  • createdAtstring
  • customClaimsarray of objects
    2 fields per item

    • keystring
    • valuestring
  • friendlyNamestring
  • idstring
  • ldapIdstring
  • namestring
  • userCountinteger

Delete signup token

delete/api/signup-tokens/{id}

Delete a signup token by ID

Path parameters

• idstringrequired

  Token ID

Response

204 No Content

Sign up initial admin user

post/api/signup/setup

Sign up and generate setup access token for initial admin user

Body application/json

• usernamestringrequired

  1 to 50 characters

• emailstring
• firstNamestring

  at most 50 characters

• lastNamestring

  at most 50 characters

• tokenstring

Response

200 OKapplication/json

13 fields

• customClaimsarray of objects
  2 fields per item

  • keystring
  • valuestring
• disabledboolean
• displayNamestring
• emailstring
• emailVerifiedboolean
• firstNamestring
• idstring
• isAdminboolean
• lastNamestring
• ldapIdstring
• localestring
• userGroupsarray of objects
  7 fields per item

  • createdAtstring
  • customClaimsarray of objects
    2 fields per item

    • keystring
    • valuestring
  • friendlyNamestring
  • idstring
  • ldapIdstring
  • namestring
  • userCountinteger
• usernamestring

List users

get/api/users

Get a paginated list of users with optional search and sorting

Query parameters

• searchstring

  Search term to filter users

• pagination[page]integer

  Page number for pagination

  defaults to 1

• pagination[limit]integer

  Number of items per page

  defaults to 20

• sort[column]string

  Column to sort by

• sort[direction]string

  Sort direction (asc or desc)

  defaults to asc

Response

200 OKapplication/json

2 fields

• dataarray of objects
  13 fields per item

  • customClaimsarray of objects
    2 fields per item

    • keystring
    • valuestring
  • disabledboolean
  • displayNamestring
  • emailstring
  • emailVerifiedboolean
  • firstNamestring
  • idstring
  • isAdminboolean
  • lastNamestring
  • ldapIdstring
  • localestring
  • userGroupsarray of objects
    7 fields per item

    • createdAtstring
    • customClaimsarray of objects
      2 fields per item

      • keystring
      • valuestring
    • friendlyNamestring
    • idstring
    • ldapIdstring
    • namestring
    • userCountinteger
  • usernamestring
• paginationobject
  4 fields

  • currentPageinteger
  • itemsPerPageinteger
  • totalItemsinteger
  • totalPagesinteger

Create user

post/api/users

Create a new user

Body application/json

• usernamestringrequired

  1 to 50 characters

• disabledboolean
• displayNamestring

  at most 100 characters

• emailstring
• emailVerifiedboolean
• firstNamestring

  at most 50 characters

• idstring
• isAdminboolean
• lastNamestring

  at most 50 characters

• localestring
• userGroupIdsarray of strings

Response

201 Createdapplication/json

13 fields

• customClaimsarray of objects
  2 fields per item

  • keystring
  • valuestring
• disabledboolean
• displayNamestring
• emailstring
• emailVerifiedboolean
• firstNamestring
• idstring
• isAdminboolean
• lastNamestring
• ldapIdstring
• localestring
• userGroupsarray of objects
  7 fields per item

  • createdAtstring
  • customClaimsarray of objects
    2 fields per item

    • keystring
    • valuestring
  • friendlyNamestring
  • idstring
  • ldapIdstring
  • namestring
  • userCountinteger
• usernamestring

Get current user

get/api/users/me

Retrieve information about the currently authenticated user

Response

200 OKapplication/json

13 fields

• customClaimsarray of objects
  2 fields per item

  • keystring
  • valuestring
• disabledboolean
• displayNamestring
• emailstring
• emailVerifiedboolean
• firstNamestring
• idstring
• isAdminboolean
• lastNamestring
• ldapIdstring
• localestring
• userGroupsarray of objects
  7 fields per item

  • createdAtstring
  • customClaimsarray of objects
    2 fields per item

    • keystring
    • valuestring
  • friendlyNamestring
  • idstring
  • ldapIdstring
  • namestring
  • userCountinteger
• usernamestring

Update current user

put/api/users/me

Update the currently authenticated user's information

Body application/json

• usernamestringrequired

  1 to 50 characters

• disabledboolean
• displayNamestring

  at most 100 characters

• emailstring
• emailVerifiedboolean
• firstNamestring

  at most 50 characters

• idstring
• isAdminboolean
• lastNamestring

  at most 50 characters

• localestring
• userGroupIdsarray of strings

Response

200 OKapplication/json

13 fields

• customClaimsarray of objects
  2 fields per item

  • keystring
  • valuestring
• disabledboolean
• displayNamestring
• emailstring
• emailVerifiedboolean
• firstNamestring
• idstring
• isAdminboolean
• lastNamestring
• ldapIdstring
• localestring
• userGroupsarray of objects
  7 fields per item

  • createdAtstring
  • customClaimsarray of objects
    2 fields per item

    • keystring
    • valuestring
  • friendlyNamestring
  • idstring
  • ldapIdstring
  • namestring
  • userCountinteger
• usernamestring

Update current user's profile picture

put/api/users/me/profile-picture

Update the currently authenticated user's profile picture

Body multipart/form-data

• filebinaryrequired

  Profile picture image file (PNG, JPG, or JPEG)

Response

204 No Content

Reset current user's profile picture

delete/api/users/me/profile-picture

Reset the currently authenticated user's profile picture to the default

Response

204 No Content

Send email verification

post/api/users/me/send-email-verification

Send an email verification to the currently authenticated user

Response

204 No Content

Verify email

post/api/users/me/verify-email

Verify the currently authenticated user's email using a verification token

Body application/json

• tokenstringrequired

Response

204 No Content

Get user by ID

get/api/users/{id}

Retrieve detailed information about a specific user

Path parameters

• idstringrequired

  User ID

Response

200 OKapplication/json

13 fields

• customClaimsarray of objects
  2 fields per item

  • keystring
  • valuestring
• disabledboolean
• displayNamestring
• emailstring
• emailVerifiedboolean
• firstNamestring
• idstring
• isAdminboolean
• lastNamestring
• ldapIdstring
• localestring
• userGroupsarray of objects
  7 fields per item

  • createdAtstring
  • customClaimsarray of objects
    2 fields per item

    • keystring
    • valuestring
  • friendlyNamestring
  • idstring
  • ldapIdstring
  • namestring
  • userCountinteger
• usernamestring

Update user

put/api/users/{id}

Update an existing user by ID

Path parameters

• idstringrequired

  User ID

Body application/json

• usernamestringrequired

  1 to 50 characters

• disabledboolean
• displayNamestring

  at most 100 characters

• emailstring
• emailVerifiedboolean
• firstNamestring

  at most 50 characters

• idstring
• isAdminboolean
• lastNamestring

  at most 50 characters

• localestring
• userGroupIdsarray of strings

Response

200 OKapplication/json

13 fields

• customClaimsarray of objects
  2 fields per item

  • keystring
  • valuestring
• disabledboolean
• displayNamestring
• emailstring
• emailVerifiedboolean
• firstNamestring
• idstring
• isAdminboolean
• lastNamestring
• ldapIdstring
• localestring
• userGroupsarray of objects
  7 fields per item

  • createdAtstring
  • customClaimsarray of objects
    2 fields per item

    • keystring
    • valuestring
  • friendlyNamestring
  • idstring
  • ldapIdstring
  • namestring
  • userCountinteger
• usernamestring

Delete user

delete/api/users/{id}

Delete a specific user by ID

Path parameters

• idstringrequired

  User ID

Response

204 No Content

Get user groups

get/api/users/{id}/groups

Retrieve all groups a specific user belongs to

Path parameters

• idstringrequired

  User ID

Response

200 OKapplication/json

8 fields per item

• allowedOidcClientsarray of objects
  8 fields per item

  • clientTypestring
  • descriptionstring
  • hasDarkLogoboolean
  • hasLogoboolean
  • idstring
  • launchURLstring
  • namestring
  • requiresReauthenticationboolean
• createdAtstring
• customClaimsarray of objects
  2 fields per item

  • keystring
  • valuestring
• friendlyNamestring
• idstring
• ldapIdstring
• namestring
• usersarray of objects
  13 fields per item

  • customClaimsarray of objects
    2 fields per item

    • keystring
    • valuestring
  • disabledboolean
  • displayNamestring
  • emailstring
  • emailVerifiedboolean
  • firstNamestring
  • idstring
  • isAdminboolean
  • lastNamestring
  • ldapIdstring
  • localestring
  • userGroupsarray of objects
    7 fields per item

    • createdAtstring
    • customClaimsarray of objects
      2 fields per item

      • keystring
      • valuestring
    • friendlyNamestring
    • idstring
    • ldapIdstring
    • namestring
    • userCountinteger
  • usernamestring

Request one-time access email (admin)

post/api/users/{id}/one-time-access-email

Request a one-time access email for a specific user (admin only)

Path parameters

• idstringrequired

  User ID

Body application/json

• ttlobject

Response

204 No Content

Create one-time access token for user (admin)

post/api/users/{id}/one-time-access-token

Generate a one-time access token for a specific user (admin only)

Path parameters

• idstringrequired

  User ID

Body application/json

object

Response

201 application/json

Update user profile picture

put/api/users/{id}/profile-picture

Update a specific user's profile picture

Path parameters

• idstringrequired

  User ID

Body multipart/form-data

• filebinaryrequired

  Profile picture image file (PNG, JPG, or JPEG)

Response

204 No Content

Reset user profile picture

delete/api/users/{id}/profile-picture

Reset a specific user's profile picture to the default

Path parameters

• idstringrequired

  User ID

Response

204 No Content

Get user profile picture

get/api/users/{id}/profile-picture.png

Retrieve a specific user's profile picture

Path parameters

• idstringrequired

  User ID

Response

200 image/png

Update user groups

put/api/users/{id}/user-groups

Update the groups a specific user belongs to

Path parameters

• idstringrequired

  User ID

Body application/json

• userGroupIdsarray of stringsrequired

Response

200 OKapplication/json

13 fields

• customClaimsarray of objects
  2 fields per item

  • keystring
  • valuestring
• disabledboolean
• displayNamestring
• emailstring
• emailVerifiedboolean
• firstNamestring
• idstring
• isAdminboolean
• lastNamestring
• ldapIdstring
• localestring
• userGroupsarray of objects
  7 fields per item

  • createdAtstring
  • customClaimsarray of objects
    2 fields per item

    • keystring
    • valuestring
  • friendlyNamestring
  • idstring
  • ldapIdstring
  • namestring
  • userCountinteger
• usernamestring

List user passkeys

get/api/users/{id}/webauthn-credentials

Retrieve all WebAuthn credentials for a specific user

Path parameters

• idstringrequired

  User ID

Response

200 OKapplication/json

10 fields per item

• aaguidstring
• attestationTypestring
• backupEligibleboolean
• backupStateboolean
• createdAtstring
• credentialIDstring
• hasIconboolean
• idstring
• namestring
• transportarray of strings

Delete user passkey

delete/api/users/{id}/webauthn-credentials/{credentialId}

Delete a specific WebAuthn credential for a user

Path parameters

• idstringrequired

  User ID

• credentialIdstringrequired

  Credential ID

Response

204 No Content

User Groups

Groups and their members.

• get/api/user-groupsList user groups
• post/api/user-groupsCreate user group
• get/api/user-groups/{id}Get user group by ID
• put/api/user-groups/{id}Update user group
• delete/api/user-groups/{id}Delete user group
• put/api/user-groups/{id}/usersUpdate users in a group

List user groups

get/api/user-groups

Get a paginated list of user groups with optional search and sorting

Query parameters

• searchstring

  Search term to filter user groups by name

• pagination[page]integer

  Page number for pagination

  defaults to 1

• pagination[limit]integer

  Number of items per page

  defaults to 20

• sort[column]string

  Column to sort by

• sort[direction]string

  Sort direction (asc or desc)

  defaults to asc

Response

200 OKapplication/json

2 fields

• dataarray of objects
  7 fields per item

  • createdAtstring
  • customClaimsarray of objects
    2 fields per item

    • keystring
    • valuestring
  • friendlyNamestring
  • idstring
  • ldapIdstring
  • namestring
  • userCountinteger
• paginationobject
  4 fields

  • currentPageinteger
  • itemsPerPageinteger
  • totalItemsinteger
  • totalPagesinteger

Create user group

post/api/user-groups

Create a new user group

Body application/json

• friendlyNamestringrequired

  2 to 50 characters

• namestringrequired

  2 to 255 characters

Response

201 Created user groupapplication/json

8 fields

• allowedOidcClientsarray of objects
  8 fields per item

  • clientTypestring
  • descriptionstring
  • hasDarkLogoboolean
  • hasLogoboolean
  • idstring
  • launchURLstring
  • namestring
  • requiresReauthenticationboolean
• createdAtstring
• customClaimsarray of objects
  2 fields per item

  • keystring
  • valuestring
• friendlyNamestring
• idstring
• ldapIdstring
• namestring
• usersarray of objects
  13 fields per item

  • customClaimsarray of objects
    2 fields per item

    • keystring
    • valuestring
  • disabledboolean
  • displayNamestring
  • emailstring
  • emailVerifiedboolean
  • firstNamestring
  • idstring
  • isAdminboolean
  • lastNamestring
  • ldapIdstring
  • localestring
  • userGroupsarray of objects
    7 fields per item

    • createdAtstring
    • customClaimsarray of objects
      2 fields per item

      • keystring
      • valuestring
    • friendlyNamestring
    • idstring
    • ldapIdstring
    • namestring
    • userCountinteger
  • usernamestring

Get user group by ID

get/api/user-groups/{id}

Retrieve detailed information about a specific user group including its users

Path parameters

• idstringrequired

  User Group ID

Response

200 OKapplication/json

8 fields

• allowedOidcClientsarray of objects
  8 fields per item

  • clientTypestring
  • descriptionstring
  • hasDarkLogoboolean
  • hasLogoboolean
  • idstring
  • launchURLstring
  • namestring
  • requiresReauthenticationboolean
• createdAtstring
• customClaimsarray of objects
  2 fields per item

  • keystring
  • valuestring
• friendlyNamestring
• idstring
• ldapIdstring
• namestring
• usersarray of objects
  13 fields per item

  • customClaimsarray of objects
    2 fields per item

    • keystring
    • valuestring
  • disabledboolean
  • displayNamestring
  • emailstring
  • emailVerifiedboolean
  • firstNamestring
  • idstring
  • isAdminboolean
  • lastNamestring
  • ldapIdstring
  • localestring
  • userGroupsarray of objects
    7 fields per item

    • createdAtstring
    • customClaimsarray of objects
      2 fields per item

      • keystring
      • valuestring
    • friendlyNamestring
    • idstring
    • ldapIdstring
    • namestring
    • userCountinteger
  • usernamestring

Update user group

put/api/user-groups/{id}

Update an existing user group by ID

Path parameters

• idstringrequired

  User Group ID

Body application/json

• friendlyNamestringrequired

  2 to 50 characters

• namestringrequired

  2 to 255 characters

Response

200 Updated user groupapplication/json

8 fields

• allowedOidcClientsarray of objects
  8 fields per item

  • clientTypestring
  • descriptionstring
  • hasDarkLogoboolean
  • hasLogoboolean
  • idstring
  • launchURLstring
  • namestring
  • requiresReauthenticationboolean
• createdAtstring
• customClaimsarray of objects
  2 fields per item

  • keystring
  • valuestring
• friendlyNamestring
• idstring
• ldapIdstring
• namestring
• usersarray of objects
  13 fields per item

  • customClaimsarray of objects
    2 fields per item

    • keystring
    • valuestring
  • disabledboolean
  • displayNamestring
  • emailstring
  • emailVerifiedboolean
  • firstNamestring
  • idstring
  • isAdminboolean
  • lastNamestring
  • ldapIdstring
  • localestring
  • userGroupsarray of objects
    7 fields per item

    • createdAtstring
    • customClaimsarray of objects
      2 fields per item

      • keystring
      • valuestring
    • friendlyNamestring
    • idstring
    • ldapIdstring
    • namestring
    • userCountinteger
  • usernamestring

Delete user group

delete/api/user-groups/{id}

Delete a specific user group by ID

Path parameters

• idstringrequired

  User Group ID

Response

204 No Content

Update users in a group

put/api/user-groups/{id}/users

Update the list of users belonging to a specific user group

Path parameters

• idstringrequired

  User Group ID

Body application/json

• userIdsarray of stringsrequired

Response

200 OKapplication/json

8 fields

• allowedOidcClientsarray of objects
  8 fields per item

  • clientTypestring
  • descriptionstring
  • hasDarkLogoboolean
  • hasLogoboolean
  • idstring
  • launchURLstring
  • namestring
  • requiresReauthenticationboolean
• createdAtstring
• customClaimsarray of objects
  2 fields per item

  • keystring
  • valuestring
• friendlyNamestring
• idstring
• ldapIdstring
• namestring
• usersarray of objects
  13 fields per item

  • customClaimsarray of objects
    2 fields per item

    • keystring
    • valuestring
  • disabledboolean
  • displayNamestring
  • emailstring
  • emailVerifiedboolean
  • firstNamestring
  • idstring
  • isAdminboolean
  • lastNamestring
  • ldapIdstring
  • localestring
  • userGroupsarray of objects
    7 fields per item

    • createdAtstring
    • customClaimsarray of objects
      2 fields per item

      • keystring
      • valuestring
    • friendlyNamestring
    • idstring
    • ldapIdstring
    • namestring
    • userCountinteger
  • usernamestring

OIDC

OIDC clients with their secrets, logos and allowed groups, plus the clients each user has authorized.

• get/api/oidc/clientsList OIDC clients
• post/api/oidc/clientsCreate OIDC client
• get/api/oidc/clients/{id}Get OIDC client
• put/api/oidc/clients/{id}Update OIDC client
• delete/api/oidc/clients/{id}Delete OIDC client
• put/api/oidc/clients/{id}/allowed-user-groupsUpdate allowed user groups
• get/api/oidc/clients/{id}/logoGet client logo
• post/api/oidc/clients/{id}/logoUpdate client logo
• delete/api/oidc/clients/{id}/logoDelete client logo
• get/api/oidc/clients/{id}/metaGet client metadata
• get/api/oidc/clients/{id}/preview/{userId}Preview OIDC client data for user
• post/api/oidc/clients/{id}/refreshRefresh client metadata document
• get/api/oidc/clients/{id}/scim-service-providerGet SCIM service provider
• get/api/oidc/clients/{id}/secretsList client secrets
• post/api/oidc/clients/{id}/secretsCreate client secret
• delete/api/oidc/clients/{id}/secrets/{secretId}Delete client secret
• post/api/oidc/introspectIntrospect OIDC tokens
• get/api/oidc/logo-presetsSearch logo presets
• get/api/oidc/userinfoGet user information
• get/api/oidc/users/me/authorized-clientsList authorized clients for current user
• delete/api/oidc/users/me/authorized-clients/{clientId}Revoke authorization for an OIDC client
• get/api/oidc/users/me/clientsList accessible OIDC clients for current user
• get/api/oidc/users/{id}/authorized-clientsList authorized clients for a user
• put/api/user-groups/{id}/allowed-oidc-clientsUpdate allowed OIDC clients

List OIDC clients

get/api/oidc/clients

Get a paginated list of OIDC clients with optional search and sorting

Query parameters

• searchstring

  Search term to filter clients by name

• pagination[page]integer

  Page number for pagination

  defaults to 1

• pagination[limit]integer

  Number of items per page

  defaults to 20

• sort[column]string

  Column to sort by

• sort[direction]string

  Sort direction (asc or desc)

  defaults to asc

Response

200 OKapplication/json

2 fields

• dataarray of objects
  21 fields per item

  • accessTokenDurationMinutesinteger
  • allowedUserGroupsarray of objects
    7 fields per item

    • createdAtstring
    • customClaimsarray of objects
      2 fields per item

      • keystring
      • valuestring
    • friendlyNamestring
    • idstring
    • ldapIdstring
    • namestring
    • userCountinteger
  • backchannelLogoutURLstring
  • callbackURLsarray of strings
  • clientTypestring
  • credentialsobject
    2 fields

    • federatedIdentitiesarray of objects
      6 fields per item

      • audiencestring
      • issuerstring
      • jwksstring
      • publicKeysarray of objects
      • replayProtectionboolean
      • subjectstring
    • secretsarray of objects

      Secrets is read-only: secrets are managed through the dedicated client secret endpoints and any value sent by a client is ignored

      5 fields per item

      • createdAtstring
      • expiresAtstring
      • idstring
      • isActiveboolean
      • prefixstring

        Prefix holds the first few characters of the secret in clear text, and is empty for secrets migrated from the single-secret column

  • descriptionstring
  • hasDarkLogoboolean
  • hasLogoboolean
  • idstring
  • isGroupRestrictedboolean
  • isPublicboolean
  • launchURLstring
  • logoutCallbackURLsarray of strings
  • namestring
  • pkceEnabledboolean
  • pkceSupportedboolean
  • refreshTokenDurationMinutesinteger
  • requiresPushedAuthorizationRequestsboolean
  • requiresReauthenticationboolean
  • skipConsentboolean
• paginationobject
  4 fields

  • currentPageinteger
  • itemsPerPageinteger
  • totalItemsinteger
  • totalPagesinteger

Create OIDC client

post/api/oidc/clients

Create a new OIDC client

Body application/json

• namestringrequired

  at most 50 characters

• accessTokenDurationMinutesinteger
• backchannelLogoutURLstring
• callbackURLsarray of strings
• credentialsobject
  2 fields

  • federatedIdentitiesarray of objects
    6 fields per item

    • audiencestring
    • issuerstring
    • jwksstring
    • publicKeysarray of objects
    • replayProtectionboolean
    • subjectstring
  • secretsarray of objects

    Secrets is read-only: secrets are managed through the dedicated client secret endpoints and any value sent by a client is ignored

    5 fields per item

    • createdAtstring
    • expiresAtstring
    • idstring
    • isActiveboolean
    • prefixstring

      Prefix holds the first few characters of the secret in clear text, and is empty for secrets migrated from the single-secret column

• darkLogoUrlstring
• descriptionstring

  at most 150 characters

• hasDarkLogoboolean
• hasLogoboolean
• idstring

  2 to 128 characters

• isGroupRestrictedboolean
• isPublicboolean
• launchURLstring
• logoUrlstring
• logoutCallbackURLsarray of strings
• pkceEnabledboolean
• refreshTokenDurationMinutesinteger
• requiresPushedAuthorizationRequestsboolean
• requiresReauthenticationboolean
• skipConsentboolean

Response

201 Created clientapplication/json

22 fields

• accessTokenDurationMinutesinteger
• allowedUserGroupsarray of objects
  7 fields per item

  • createdAtstring
  • customClaimsarray of objects
    2 fields per item

    • keystring
    • valuestring
  • friendlyNamestring
  • idstring
  • ldapIdstring
  • namestring
  • userCountinteger
• backchannelLogoutURLstring
• callbackURLsarray of strings
• clientTypestring
• createdSecretobject
  6 fields

  • createdAtstring
  • expiresAtstring
  • idstring
  • isActiveboolean
  • prefixstring

    Prefix holds the first few characters of the secret in clear text, and is empty for secrets migrated from the single-secret column

  • secretstring
• credentialsobject
  2 fields

  • federatedIdentitiesarray of objects
    6 fields per item

    • audiencestring
    • issuerstring
    • jwksstring
    • publicKeysarray of objects
    • replayProtectionboolean
    • subjectstring
  • secretsarray of objects

    Secrets is read-only: secrets are managed through the dedicated client secret endpoints and any value sent by a client is ignored

    5 fields per item

    • createdAtstring
    • expiresAtstring
    • idstring
    • isActiveboolean
    • prefixstring

      Prefix holds the first few characters of the secret in clear text, and is empty for secrets migrated from the single-secret column

• descriptionstring
• hasDarkLogoboolean
• hasLogoboolean
• idstring
• isGroupRestrictedboolean
• isPublicboolean
• launchURLstring
• logoutCallbackURLsarray of strings
• namestring
• pkceEnabledboolean
• pkceSupportedboolean
• refreshTokenDurationMinutesinteger
• requiresPushedAuthorizationRequestsboolean
• requiresReauthenticationboolean
• skipConsentboolean

Get OIDC client

get/api/oidc/clients/{id}

Get detailed information about an OIDC client

Path parameters

• idstringrequired

  Client ID

Response

200 Client informationapplication/json

21 fields

• accessTokenDurationMinutesinteger
• allowedUserGroupsarray of objects
  7 fields per item

  • createdAtstring
  • customClaimsarray of objects
    2 fields per item

    • keystring
    • valuestring
  • friendlyNamestring
  • idstring
  • ldapIdstring
  • namestring
  • userCountinteger
• backchannelLogoutURLstring
• callbackURLsarray of strings
• clientTypestring
• credentialsobject
  2 fields

  • federatedIdentitiesarray of objects
    6 fields per item

    • audiencestring
    • issuerstring
    • jwksstring
    • publicKeysarray of objects
    • replayProtectionboolean
    • subjectstring
  • secretsarray of objects

    Secrets is read-only: secrets are managed through the dedicated client secret endpoints and any value sent by a client is ignored

    5 fields per item

    • createdAtstring
    • expiresAtstring
    • idstring
    • isActiveboolean
    • prefixstring

      Prefix holds the first few characters of the secret in clear text, and is empty for secrets migrated from the single-secret column

• descriptionstring
• hasDarkLogoboolean
• hasLogoboolean
• idstring
• isGroupRestrictedboolean
• isPublicboolean
• launchURLstring
• logoutCallbackURLsarray of strings
• namestring
• pkceEnabledboolean
• pkceSupportedboolean
• refreshTokenDurationMinutesinteger
• requiresPushedAuthorizationRequestsboolean
• requiresReauthenticationboolean
• skipConsentboolean

Update OIDC client

put/api/oidc/clients/{id}

Update an existing OIDC client

Path parameters

• idstringrequired

  Client ID

Body application/json

• namestringrequired

  at most 50 characters

• accessTokenDurationMinutesinteger
• backchannelLogoutURLstring
• callbackURLsarray of strings
• credentialsobject
  2 fields

  • federatedIdentitiesarray of objects
    6 fields per item

    • audiencestring
    • issuerstring
    • jwksstring
    • publicKeysarray of objects
    • replayProtectionboolean
    • subjectstring
  • secretsarray of objects

    Secrets is read-only: secrets are managed through the dedicated client secret endpoints and any value sent by a client is ignored

    5 fields per item

    • createdAtstring
    • expiresAtstring
    • idstring
    • isActiveboolean
    • prefixstring

      Prefix holds the first few characters of the secret in clear text, and is empty for secrets migrated from the single-secret column

• darkLogoUrlstring
• descriptionstring

  at most 150 characters

• hasDarkLogoboolean
• hasLogoboolean
• isGroupRestrictedboolean
• isPublicboolean
• launchURLstring
• logoUrlstring
• logoutCallbackURLsarray of strings
• pkceEnabledboolean
• refreshTokenDurationMinutesinteger
• requiresPushedAuthorizationRequestsboolean
• requiresReauthenticationboolean
• skipConsentboolean

Response

200 Updated clientapplication/json

21 fields

• accessTokenDurationMinutesinteger
• allowedUserGroupsarray of objects
  7 fields per item

  • createdAtstring
  • customClaimsarray of objects
    2 fields per item

    • keystring
    • valuestring
  • friendlyNamestring
  • idstring
  • ldapIdstring
  • namestring
  • userCountinteger
• backchannelLogoutURLstring
• callbackURLsarray of strings
• clientTypestring
• credentialsobject
  2 fields

  • federatedIdentitiesarray of objects
    6 fields per item

    • audiencestring
    • issuerstring
    • jwksstring
    • publicKeysarray of objects
    • replayProtectionboolean
    • subjectstring
  • secretsarray of objects

    Secrets is read-only: secrets are managed through the dedicated client secret endpoints and any value sent by a client is ignored

    5 fields per item

    • createdAtstring
    • expiresAtstring
    • idstring
    • isActiveboolean
    • prefixstring

      Prefix holds the first few characters of the secret in clear text, and is empty for secrets migrated from the single-secret column

• descriptionstring
• hasDarkLogoboolean
• hasLogoboolean
• idstring
• isGroupRestrictedboolean
• isPublicboolean
• launchURLstring
• logoutCallbackURLsarray of strings
• namestring
• pkceEnabledboolean
• pkceSupportedboolean
• refreshTokenDurationMinutesinteger
• requiresPushedAuthorizationRequestsboolean
• requiresReauthenticationboolean
• skipConsentboolean

Delete OIDC client

delete/api/oidc/clients/{id}

Delete an OIDC client by ID

Path parameters

• idstringrequired

  Client ID

Response

204 No Content

Update allowed user groups

put/api/oidc/clients/{id}/allowed-user-groups

Update the user groups allowed to access an OIDC client

Path parameters

• idstringrequired

  Client ID

Body application/json

• userGroupIdsarray of stringsrequired

Response

200 Updated clientapplication/json

20 fields

• accessTokenDurationMinutesinteger
• backchannelLogoutURLstring
• callbackURLsarray of strings
• clientTypestring
• credentialsobject
  2 fields

  • federatedIdentitiesarray of objects
    6 fields per item

    • audiencestring
    • issuerstring
    • jwksstring
    • publicKeysarray of objects
    • replayProtectionboolean
    • subjectstring
  • secretsarray of objects

    Secrets is read-only: secrets are managed through the dedicated client secret endpoints and any value sent by a client is ignored

    5 fields per item

    • createdAtstring
    • expiresAtstring
    • idstring
    • isActiveboolean
    • prefixstring

      Prefix holds the first few characters of the secret in clear text, and is empty for secrets migrated from the single-secret column

• descriptionstring
• hasDarkLogoboolean
• hasLogoboolean
• idstring
• isGroupRestrictedboolean
• isPublicboolean
• launchURLstring
• logoutCallbackURLsarray of strings
• namestring
• pkceEnabledboolean
• pkceSupportedboolean
• refreshTokenDurationMinutesinteger
• requiresPushedAuthorizationRequestsboolean
• requiresReauthenticationboolean
• skipConsentboolean

Get client logo

get/api/oidc/clients/{id}/logo

Get the logo image for an OIDC client

Path parameters

• idstringrequired

  Client ID

Query parameters

• lightboolean

  Light mode logo (true) or dark mode logo (false)

Response

200 image/png

Update client logo

post/api/oidc/clients/{id}/logo

Upload or update the logo for an OIDC client

Path parameters

• idstringrequired

  Client ID

Query parameters

• lightboolean

  Light mode logo (true) or dark mode logo (false)

Body multipart/form-data

• filebinaryrequired

  Logo image file (PNG, JPG, or SVG)

Response

204 No Content

Delete client logo

delete/api/oidc/clients/{id}/logo

Delete the logo for an OIDC client

Path parameters

• idstringrequired

  Client ID

Query parameters

• lightboolean

  Light mode logo (true) or dark mode logo (false)

Response

204 No Content

Get client metadata

get/api/oidc/clients/{id}/meta

Get OIDC client metadata for discovery and configuration

Path parameters

• idstringrequired

  Client ID

Response

200 Client metadataapplication/json

8 fields

• clientTypestring
• descriptionstring
• hasDarkLogoboolean
• hasLogoboolean
• idstring
• launchURLstring
• namestring
• requiresReauthenticationboolean

Preview OIDC client data for user

get/api/oidc/clients/{id}/preview/{userId}

Get a preview of the OIDC data (ID token, access token, userinfo) that would be sent to the client for a specific user

Path parameters

• idstringrequired

  Client ID

• userIdstringrequired

  User ID to preview data for

Query parameters

• scopesstring

  Scopes to include in the preview (comma-separated)

Response

200 Preview data including ID token, access token, and userinfo payloadsapplication/json

3 fields

• accessTokenmap of values
• idTokenmap of values
• userInfomap of values

Refresh client metadata document

post/api/oidc/clients/{id}/refresh

Force a re-fetch of the OAuth Client ID Metadata Document for a CIMD client

Path parameters

• idstringrequired

  Client ID

Response

200 Refreshed clientapplication/json

21 fields

• accessTokenDurationMinutesinteger
• allowedUserGroupsarray of objects
  7 fields per item

  • createdAtstring
  • customClaimsarray of objects
    2 fields per item

    • keystring
    • valuestring
  • friendlyNamestring
  • idstring
  • ldapIdstring
  • namestring
  • userCountinteger
• backchannelLogoutURLstring
• callbackURLsarray of strings
• clientTypestring
• credentialsobject
  2 fields

  • federatedIdentitiesarray of objects
    6 fields per item

    • audiencestring
    • issuerstring
    • jwksstring
    • publicKeysarray of objects
    • replayProtectionboolean
    • subjectstring
  • secretsarray of objects

    Secrets is read-only: secrets are managed through the dedicated client secret endpoints and any value sent by a client is ignored

    5 fields per item

    • createdAtstring
    • expiresAtstring
    • idstring
    • isActiveboolean
    • prefixstring

      Prefix holds the first few characters of the secret in clear text, and is empty for secrets migrated from the single-secret column

• descriptionstring
• hasDarkLogoboolean
• hasLogoboolean
• idstring
• isGroupRestrictedboolean
• isPublicboolean
• launchURLstring
• logoutCallbackURLsarray of strings
• namestring
• pkceEnabledboolean
• pkceSupportedboolean
• refreshTokenDurationMinutesinteger
• requiresPushedAuthorizationRequestsboolean
• requiresReauthenticationboolean
• skipConsentboolean

Get SCIM service provider

get/api/oidc/clients/{id}/scim-service-provider

Get the SCIM service provider configuration for an OIDC client

Path parameters

• idstringrequired

  Client ID

Response

200 SCIM service provider configurationapplication/json

6 fields

• createdAtstring
• endpointstring
• idstring
• lastSyncedAtstring
• oidcClientobject
  8 fields

  • clientTypestring
  • descriptionstring
  • hasDarkLogoboolean
  • hasLogoboolean
  • idstring
  • launchURLstring
  • namestring
  • requiresReauthenticationboolean
• tokenstring

List client secrets

get/api/oidc/clients/{id}/secrets

List the secrets of an OIDC client, without disclosing their values

Path parameters

• idstringrequired

  Client ID

Response

200 Client secretsapplication/json

5 fields per item

• createdAtstring
• expiresAtstring
• idstring
• isActiveboolean
• prefixstring

  Prefix holds the first few characters of the secret in clear text, and is empty for secrets migrated from the single-secret column

Create client secret

post/api/oidc/clients/{id}/secrets

Add a new secret to an OIDC client, leaving the existing ones usable. The value is only returned by this endpoint and cannot be retrieved later.

Path parameters

• idstringrequired

  Client ID

Body application/json

• expiresAtstring

  ExpiresAt makes the secret unusable after the given time (if nil, secrets don't expire)

• secretstring

  Secret allows callers to supply their own value instead of having Pocket ID generate one

  at least 16 characters

Response

201 Created client secretapplication/json

6 fields

• createdAtstring
• expiresAtstring
• idstring
• isActiveboolean
• prefixstring

  Prefix holds the first few characters of the secret in clear text, and is empty for secrets migrated from the single-secret column

• secretstring

Delete client secret

delete/api/oidc/clients/{id}/secrets/{secretId}

Delete a single secret of an OIDC client, making it immediately unusable

Path parameters

• idstringrequired

  Client ID

• secretIdstringrequired

  Client secret ID

Response

204 No content

Introspect OIDC tokens

post/api/oidc/introspect

Pass a token to verify if it is considered valid.

Body multipart/form-data

• tokenstringrequired

  The token to be introspected.

Response

200 application/json

Search logo presets

get/api/oidc/logo-presets

Search the selfh.st icon collection for logos that can be used for OIDC clients

Query parameters

• searchstring

  Search term matched against the icon name

Response

200 OKapplication/json

4 fields per item

• darkLogoUrlstring
• logoUrlstring
• namestring
• referencestring

Get user information

get/api/oidc/userinfo

Get user information based on the access token

Response

200 application/json

List authorized clients for current user

get/api/oidc/users/me/authorized-clients

Get a paginated list of OIDC clients that the current user has authorized

Query parameters

• pagination[page]integer

  Page number for pagination

  defaults to 1

• pagination[limit]integer

  Number of items per page

  defaults to 20

• sort[column]string

  Column to sort by

• sort[direction]string

  Sort direction (asc or desc)

  defaults to asc

• filters[hasLaunchURL]boolean

  Filter clients by whether a launch URL is configured

Response

200 OKapplication/json

2 fields

• dataarray of objects
  3 fields per item

  • clientobject
    8 fields

    • clientTypestring
    • descriptionstring
    • hasDarkLogoboolean
    • hasLogoboolean
    • idstring
    • launchURLstring
    • namestring
    • requiresReauthenticationboolean
  • lastUsedAtstring
  • scopestring
• paginationobject
  4 fields

  • currentPageinteger
  • itemsPerPageinteger
  • totalItemsinteger
  • totalPagesinteger

Revoke authorization for an OIDC client

delete/api/oidc/users/me/authorized-clients/{clientId}

Revoke the authorization for a specific OIDC client for the current user

Path parameters

• clientIdstringrequired

  Client ID to revoke authorization for

Response

204 No Content

List accessible OIDC clients for current user

get/api/oidc/users/me/clients

Get a list of OIDC clients that the current user can access

Query parameters

• pagination[page]integer

  Page number for pagination

  defaults to 1

• pagination[limit]integer

  Number of items per page

  defaults to 20

• sort[column]string

  Column to sort by

• sort[direction]string

  Sort direction (asc or desc)

  defaults to asc

• filters[hasLaunchURL]boolean

  Filter clients by whether a launch URL is configured

Response

200 OKapplication/json

2 fields

• dataarray of objects
  9 fields per item

  • clientTypestring
  • descriptionstring
  • hasDarkLogoboolean
  • hasLogoboolean
  • idstring
  • lastUsedAtstring
  • launchURLstring
  • namestring
  • requiresReauthenticationboolean
• paginationobject
  4 fields

  • currentPageinteger
  • itemsPerPageinteger
  • totalItemsinteger
  • totalPagesinteger

List authorized clients for a user

get/api/oidc/users/{id}/authorized-clients

Get a paginated list of OIDC clients that a specific user has authorized

Path parameters

• idstringrequired

  User ID

Query parameters

• pagination[page]integer

  Page number for pagination

  defaults to 1

• pagination[limit]integer

  Number of items per page

  defaults to 20

• sort[column]string

  Column to sort by

• sort[direction]string

  Sort direction (asc or desc)

  defaults to asc

• filters[hasLaunchURL]boolean

  Filter clients by whether a launch URL is configured

Response

200 OKapplication/json

2 fields

• dataarray of objects
  3 fields per item

  • clientobject
    8 fields

    • clientTypestring
    • descriptionstring
    • hasDarkLogoboolean
    • hasLogoboolean
    • idstring
    • launchURLstring
    • namestring
    • requiresReauthenticationboolean
  • lastUsedAtstring
  • scopestring
• paginationobject
  4 fields

  • currentPageinteger
  • itemsPerPageinteger
  • totalItemsinteger
  • totalPagesinteger

Update allowed OIDC clients

put/api/user-groups/{id}/allowed-oidc-clients

Update the OIDC clients allowed for a specific user group

Path parameters

• idstringrequired

  User Group ID

Body application/json

• oidcClientIdsarray of stringsrequired

Response

200 Updated user groupapplication/json

8 fields

• allowedOidcClientsarray of objects
  8 fields per item

  • clientTypestring
  • descriptionstring
  • hasDarkLogoboolean
  • hasLogoboolean
  • idstring
  • launchURLstring
  • namestring
  • requiresReauthenticationboolean
• createdAtstring
• customClaimsarray of objects
  2 fields per item

  • keystring
  • valuestring
• friendlyNamestring
• idstring
• ldapIdstring
• namestring
• usersarray of objects
  13 fields per item

  • customClaimsarray of objects
    2 fields per item

    • keystring
    • valuestring
  • disabledboolean
  • displayNamestring
  • emailstring
  • emailVerifiedboolean
  • firstNamestring
  • idstring
  • isAdminboolean
  • lastNamestring
  • ldapIdstring
  • localestring
  • userGroupsarray of objects
    7 fields per item

    • createdAtstring
    • customClaimsarray of objects
      2 fields per item

      • keystring
      • valuestring
    • friendlyNamestring
    • idstring
    • ldapIdstring
    • namestring
    • userCountinteger
  • usernamestring

APIs

Your own APIs, their permissions and the clients that may request them.

• get/api/api-access/{clientId}/apisList APIs a client may access
• get/api/api-access/{clientId}/assignable-apisList APIs a client can still be granted access to
• get/api/apisList APIs
• post/api/apisCreate API
• get/api/apis/{id}Get API by ID
• put/api/apis/{id}Update API
• delete/api/apis/{id}Delete API
• get/api/apis/{id}/assignable-clientsList clients that can still be granted access to an API
• put/api/apis/{id}/cimd-accessUpdate metadata document client access
• get/api/apis/{id}/clientsList clients with access to an API
• put/api/apis/{id}/clients/{clientId}Update a client's access to an API
• delete/api/apis/{id}/clients/{clientId}Revoke a client's access to an API
• put/api/apis/{id}/permissionsUpdate API permissions

List APIs a client may access

get/api/api-access/{clientId}/apis

Get every API the OIDC client may request tokens for, with its access and permissions split into user-delegated and client (machine-to-machine) access

Path parameters

• clientIdstringrequired

  OIDC Client ID

Response

200 OKapplication/json

7 fields per item

• apiobject
  6 fields

  • allowCimdClientsboolean
  • createdAtstring
  • idstring
  • namestring
  • permissionsarray of objects
    5 fields per item

    • allowedForCimdClientsboolean
    • descriptionstring
    • idstring
    • keystring
    • namestring
  • resourcestring
• cimdGrantedAccessboolean
• cimdGrantedPermissionIdsarray of strings
• clientAccessboolean
• clientPermissionIdsarray of strings
• userDelegatedAccessboolean
• userDelegatedPermissionIdsarray of strings

List APIs a client can still be granted access to

get/api/api-access/{clientId}/assignable-apis

Get a paginated list of APIs the OIDC client cannot already reach

Path parameters

• clientIdstringrequired

  OIDC Client ID

Query parameters

• searchstring

  Search term to filter APIs by name or resource

• pagination[page]integer

  Page number for pagination

  defaults to 1

• pagination[limit]integer

  Number of items per page

  defaults to 20

• sort[column]string

  Column to sort by

• sort[direction]string

  Sort direction (asc or desc)

  defaults to asc

Response

200 OKapplication/json

2 fields

• dataarray of objects
  6 fields per item

  • allowCimdClientsboolean
  • createdAtstring
  • idstring
  • namestring
  • permissionsarray of objects
    5 fields per item

    • allowedForCimdClientsboolean
    • descriptionstring
    • idstring
    • keystring
    • namestring
  • resourcestring
• paginationobject
  4 fields

  • currentPageinteger
  • itemsPerPageinteger
  • totalItemsinteger
  • totalPagesinteger

List APIs

get/api/apis

Get a paginated list of APIs with optional search and sorting

Query parameters

• searchstring

  Search term to filter APIs by name or resource

• pagination[page]integer

  Page number for pagination

  defaults to 1

• pagination[limit]integer

  Number of items per page

  defaults to 20

• sort[column]string

  Column to sort by

• sort[direction]string

  Sort direction (asc or desc)

  defaults to asc

Response

200 OKapplication/json

2 fields

• dataarray of objects
  6 fields per item

  • allowCimdClientsboolean
  • createdAtstring
  • idstring
  • namestring
  • permissionsarray of objects
    5 fields per item

    • allowedForCimdClientsboolean
    • descriptionstring
    • idstring
    • keystring
    • namestring
  • resourcestring
• paginationobject
  4 fields

  • currentPageinteger
  • itemsPerPageinteger
  • totalItemsinteger
  • totalPagesinteger

Create API

post/api/apis

Create a new API resource server

Body application/json

• namestringrequired

  1 to 50 characters

• resourcestringrequired

  at most 350 characters

Response

201 Created APIapplication/json

6 fields

• allowCimdClientsboolean
• createdAtstring
• idstring
• namestring
• permissionsarray of objects
  5 fields per item

  • allowedForCimdClientsboolean
  • descriptionstring
  • idstring
  • keystring
  • namestring
• resourcestring

Get API by ID

get/api/apis/{id}

Retrieve a single API including its permissions

Path parameters

• idstringrequired

  API ID

Response

200 OKapplication/json

6 fields

• allowCimdClientsboolean
• createdAtstring
• idstring
• namestring
• permissionsarray of objects
  5 fields per item

  • allowedForCimdClientsboolean
  • descriptionstring
  • idstring
  • keystring
  • namestring
• resourcestring

Update API

put/api/apis/{id}

Update an existing API by ID

Path parameters

• idstringrequired

  API ID

Body application/json

• namestringrequired

  1 to 50 characters

Response

200 Updated APIapplication/json

6 fields

• allowCimdClientsboolean
• createdAtstring
• idstring
• namestring
• permissionsarray of objects
  5 fields per item

  • allowedForCimdClientsboolean
  • descriptionstring
  • idstring
  • keystring
  • namestring
• resourcestring

Delete API

delete/api/apis/{id}

Delete an API by ID

Path parameters

• idstringrequired

  API ID

Response

204 No Content

List clients that can still be granted access to an API

get/api/apis/{id}/assignable-clients

Get a paginated list of OIDC clients that have no grant on the API yet

Path parameters

• idstringrequired

  API ID

Query parameters

• searchstring

  Search term to filter clients by name

• pagination[page]integer

  Page number for pagination

  defaults to 1

• pagination[limit]integer

  Number of items per page

  defaults to 20

• sort[column]string

  Column to sort by

• sort[direction]string

  Sort direction (asc or desc)

  defaults to asc

Response

200 OKapplication/json

2 fields

• dataarray of objects
  6 fields per item

  • clientTypestring
  • hasDarkLogoboolean
  • hasLogoboolean
  • idstring
  • isPublicboolean
  • namestring
• paginationobject
  4 fields

  • currentPageinteger
  • itemsPerPageinteger
  • totalItemsinteger
  • totalPagesinteger

Update metadata document client access

put/api/apis/{id}/cimd-access

Replace which permissions of an API every client registered through a Client ID Metadata Document may request

Path parameters

• idstringrequired

  API ID

Body application/json

• permissionIdsarray of stringsrequired
• enabledboolean

Response

200 Updated APIapplication/json

6 fields

• allowCimdClientsboolean
• createdAtstring
• idstring
• namestring
• permissionsarray of objects
  5 fields per item

  • allowedForCimdClientsboolean
  • descriptionstring
  • idstring
  • keystring
  • namestring
• resourcestring

List clients with access to an API

get/api/apis/{id}/clients

Get a paginated list of OIDC clients that may reach the API, with their permissions split into user-delegated and client (machine-to-machine) access

Path parameters

• idstringrequired

  API ID

Query parameters

• searchstring

  Search term to filter clients by name

• pagination[page]integer

  Page number for pagination

  defaults to 1

• pagination[limit]integer

  Number of items per page

  defaults to 20

• sort[column]string

  Column to sort by

• sort[direction]string

  Sort direction (asc or desc)

  defaults to asc

Response

200 OKapplication/json

2 fields

• dataarray of objects
  7 fields per item

  • cimdGrantedAccessboolean
  • cimdGrantedPermissionIdsarray of strings
  • clientobject
    6 fields

    • clientTypestring
    • hasDarkLogoboolean
    • hasLogoboolean
    • idstring
    • isPublicboolean
    • namestring
  • clientAccessboolean
  • clientPermissionIdsarray of strings
  • userDelegatedAccessboolean
  • userDelegatedPermissionIdsarray of strings
• paginationobject
  4 fields

  • currentPageinteger
  • itemsPerPageinteger
  • totalItemsinteger
  • totalPagesinteger

Update a client's access to an API

put/api/apis/{id}/clients/{clientId}

Replace the permissions of this API a single OIDC client may request, leaving its grants on other APIs untouched

Path parameters

• idstringrequired

  API ID

• clientIdstringrequired

  OIDC Client ID

Body application/json

• clientPermissionIdsarray of stringsrequired
• userDelegatedPermissionIdsarray of stringsrequired
• clientAccessboolean
• userDelegatedAccessboolean

Response

200 OKapplication/json

4 fields

• clientAccessboolean
• clientPermissionIdsarray of strings
• userDelegatedAccessboolean
• userDelegatedPermissionIdsarray of strings

Revoke a client's access to an API

delete/api/apis/{id}/clients/{clientId}

Remove every permission of this API a single OIDC client was allowed to request

Path parameters

• idstringrequired

  API ID

• clientIdstringrequired

  OIDC Client ID

Response

204 No Content

Update API permissions

put/api/apis/{id}/permissions

Replace the full set of permissions for an API

Path parameters

• idstringrequired

  API ID

Body application/json

• permissionsarray of objects
  3 fields per item

  • keystringrequired

    1 to 128 characters

  • namestringrequired

    1 to 50 characters

  • descriptionstring

    at most 200 characters

Response

200 Updated APIapplication/json

6 fields

• allowCimdClientsboolean
• createdAtstring
• idstring
• namestring
• permissionsarray of objects
  5 fields per item

  • allowedForCimdClientsboolean
  • descriptionstring
  • idstring
  • keystring
  • namestring
• resourcestring

Custom Claims

Extra claims that Pocket ID adds to the tokens of a user or of every member of a group.

• get/api/custom-claims/suggestionsGet custom claim suggestions
• put/api/custom-claims/user-group/{userGroupId}Update custom claims for a user group
• put/api/custom-claims/user/{userId}Update custom claims for a user

Get custom claim suggestions

get/api/custom-claims/suggestions

Get a list of suggested custom claim names

Response

200 application/json

Update custom claims for a user group

put/api/custom-claims/user-group/{userGroupId}

Update or create custom claims for a specific user group

Path parameters

• userGroupIdstringrequired

  User Group ID

Body application/json

An array, with these fields per item:

• keystringrequired
• valuestringrequired

Response

200 Updated custom claimsapplication/json

2 fields per item

• keystring
• valuestring

Update custom claims for a user

put/api/custom-claims/user/{userId}

Update or create custom claims for a specific user

Path parameters

• userIdstringrequired

  User ID

Body application/json

An array, with these fields per item:

• keystringrequired
• valuestringrequired

Response

200 Updated custom claimsapplication/json

2 fields per item

• keystring
• valuestring

API Keys

Keys for this REST API.

• get/api/api-keysList API keys
• post/api/api-keysCreate API key
• delete/api/api-keys/{id}Revoke API key
• post/api/api-keys/{id}/renewRenew API key

List API keys

get/api/api-keys

Get a paginated list of API keys belonging to the current user

Query parameters

• pagination[page]integer

  Page number for pagination

  defaults to 1

• pagination[limit]integer

  Number of items per page

  defaults to 20

• sort[column]string

  Column to sort by

• sort[direction]string

  Sort direction (asc or desc)

  defaults to asc

Response

200 OKapplication/json

2 fields

• dataarray of objects
  7 fields per item

  • createdAtstring
  • descriptionstring
  • expirationEmailSentboolean
  • expiresAtstring
  • idstring
  • lastUsedAtstring
  • namestring
• paginationobject
  4 fields

  • currentPageinteger
  • itemsPerPageinteger
  • totalItemsinteger
  • totalPagesinteger

Create API key

post/api/api-keys

Create a new API key for the current user

Body application/json

• expiresAtstringrequired
• namestringrequired

  3 to 50 characters

• descriptionstring

Response

201 Created API key with tokenapplication/json

2 fields

• apiKeyobject
  7 fields

  • createdAtstring
  • descriptionstring
  • expirationEmailSentboolean
  • expiresAtstring
  • idstring
  • lastUsedAtstring
  • namestring
• tokenstring

Revoke API key

delete/api/api-keys/{id}

Revoke (delete) an existing API key by ID

Path parameters

• idstringrequired

  API Key ID

Response

204 No Content

Renew API key

post/api/api-keys/{id}/renew

Renew an existing API key by ID

Path parameters

• idstringrequired

  API Key ID

Response

200 Renewed API key with new tokenapplication/json

2 fields

• apiKeyobject
  7 fields

  • createdAtstring
  • descriptionstring
  • expirationEmailSentboolean
  • expiresAtstring
  • idstring
  • lastUsedAtstring
  • namestring
• tokenstring

Application Configuration

The settings of the Application Configuration page, the LDAP sync and the test email.

• get/api/application-configurationList public application configurations
• put/api/application-configurationUpdate application configurations
• get/api/application-configuration/allList all application configurations
• post/api/application-configuration/sync-ldapSynchronize LDAP
• post/api/application-configuration/test-emailSend test email

List public application configurations

get/api/application-configuration

Get all public application configurations

Response

200 OKapplication/json

3 fields per item

• keystring
• typestring
• valuestring

Update application configurations

put/api/application-configuration

Update application configuration settings

Body application/json

• allowOwnAccountEditstringrequired
• allowUserSignupsstringrequired

  One of disabled, withToken, open

• appNamestringrequired

  1 to 30 characters

• autoCreateOidcClientSecretstringrequired
• disableAnimationsstringrequired
• emailApiKeyExpirationEnabledstringrequired
• emailLoginNotificationEnabledstringrequired
• emailOneTimeAccessAsAdminEnabledstringrequired
• emailOneTimeAccessAsUnauthenticatedEnabledstringrequired
• emailVerificationEnabledstringrequired
• emailsVerifiedstringrequired
• homePageUrlstringrequired
• ldapEnabledstringrequired
• ldapSkipCertVerifystringrequired
• ldapSoftDeleteUsersstringrequired
• oidcClientLogoPresetsEnabledstringrequired
• requireUserEmailstringrequired
• sessionDurationstringrequired
• smtpSkipCertVerifystringrequired
• smtpTlsstringrequired

  One of none, starttls, tls

• webauthnAllowSyncedPasskeysstringrequired
• webauthnAuthenticatorAttachmentstringrequired

  One of any, platform, cross-platform

• webauthnUserVerificationstringrequired

  One of required, preferred

• accentColorstring
• cimdUrlAllowliststring
• ldapAdminGroupNamestring
• ldapAttributeGroupMemberstring
• ldapAttributeGroupNamestring
• ldapAttributeGroupUniqueIdentifierstring
• ldapAttributeUserDisplayNamestring
• ldapAttributeUserEmailstring
• ldapAttributeUserFirstNamestring
• ldapAttributeUserLastNamestring
• ldapAttributeUserProfilePicturestring
• ldapAttributeUserUniqueIdentifierstring
• ldapAttributeUserUsernamestring
• ldapBasestring
• ldapBindDnstring
• ldapBindPasswordstring
• ldapUrlstring
• ldapUserGroupSearchFilterstring
• ldapUserSearchFilterstring
• signupDefaultCustomClaimsstring
• signupDefaultUserGroupIDsstring
• smtpFromstring
• smtpHoststring
• smtpPasswordstring
• smtpPortstring
• smtpUserstring

Response

200 OKapplication/json

4 fields per item

• isPublicboolean
• keystring
• typestring
• valuestring

List all application configurations

get/api/application-configuration/all

Get all application configurations including private ones

Response

200 OKapplication/json

4 fields per item

• isPublicboolean
• keystring
• typestring
• valuestring

Synchronize LDAP

post/api/application-configuration/sync-ldap

Manually trigger LDAP synchronization

Response

204 No Content

Send test email

post/api/application-configuration/test-email

Send a test email to verify email configuration

Response

204 No Content

Application Images

The logo, favicon, background, email logo and default profile picture.

• get/api/application-images/backgroundGet background image
• put/api/application-images/backgroundUpdate background image
• delete/api/application-images/backgroundDelete background image
• get/api/application-images/default-profile-pictureGet default profile picture image
• put/api/application-images/default-profile-pictureUpdate default profile picture image
• delete/api/application-images/default-profile-pictureDelete default profile picture image
• get/api/application-images/emailGet email logo image
• put/api/application-images/emailUpdate email logo
• get/api/application-images/faviconGet favicon
• put/api/application-images/faviconUpdate favicon
• get/api/application-images/logoGet logo image
• put/api/application-images/logoUpdate logo
• delete/api/application-images/logoDelete logo image

Get background image

get/api/application-images/background

Get the background image for the application

Response

200 image/png

Update background image

put/api/application-images/background

Update the application background image

Body multipart/form-data

• filebinaryrequired

  Background image file

Response

204 No Content

Delete background image

delete/api/application-images/background

Delete the application background image

Response

204 No Content

Get default profile picture image

get/api/application-images/default-profile-picture

Get the default profile picture image for the application

Response

200 image/png

Update default profile picture image

put/api/application-images/default-profile-picture

Update the default profile picture image

Body multipart/form-data

• filebinaryrequired

  Profile picture image file

Response

204 No Content

Delete default profile picture image

delete/api/application-images/default-profile-picture

Delete the default profile picture image

Response

204 No Content

Get email logo image

get/api/application-images/email

Get the email logo image for use in emails

Response

200 image/png

Update email logo

put/api/application-images/email

Update the email logo for use in emails

Body multipart/form-data

• filebinaryrequired

  Email logo image file

Response

204 No Content

Get favicon

get/api/application-images/favicon

Get the favicon for the application

Response

200 image/x-icon

Update favicon

put/api/application-images/favicon

Update the application favicon

Body multipart/form-data

• filebinaryrequired

  Favicon file (.svg/.png/.ico)

Response

204 No Content

Get logo image

get/api/application-images/logo

Get the logo image for the application

Query parameters

• lightboolean

  Light mode logo (true) or dark mode logo (false)

• defaultboolean

  Return the bundled default logo if no custom logo is set (default true)

Response

200 image/png

Update logo

put/api/application-images/logo

Update the application logo

Query parameters

• lightboolean

  Light mode logo (true) or dark mode logo (false)

Body multipart/form-data

• filebinaryrequired

  Logo image file

Response

204 No Content

Delete logo image

delete/api/application-images/logo

Delete the custom application logo and restore the default logo

Query parameters

• lightboolean

  Light mode logo (true) or dark mode logo (false)

Response

204 No Content

Audit Logs

Sign-ins and other security events, of the current user or of everyone.

• get/api/audit-logsList audit logs
• get/api/audit-logs/allList all audit logs
• get/api/audit-logs/filters/client-namesList client names
• get/api/audit-logs/filters/usersList users with IDs

List audit logs

get/api/audit-logs

Get a paginated list of audit logs for the current user

Query parameters

• pagination[page]integer

  Page number for pagination

  defaults to 1

• pagination[limit]integer

  Number of items per page

  defaults to 20

• sort[column]string

  Column to sort by

• sort[direction]string

  Sort direction (asc or desc)

  defaults to asc

Response

200 OKapplication/json

2 fields

• dataarray of objects
  11 fields per item

  • actorUsernamestring
  • citystring
  • countrystring
  • createdAtstring
  • datamap of strings
  • devicestring
  • eventstring
  • idstring
  • ipAddressstring
  • userIDstring
  • usernamestring
• paginationobject
  4 fields

  • currentPageinteger
  • itemsPerPageinteger
  • totalItemsinteger
  • totalPagesinteger

List all audit logs

get/api/audit-logs/all

Get a paginated list of all audit logs (admin only)

Query parameters

• pagination[page]integer

  Page number for pagination

  defaults to 1

• pagination[limit]integer

  Number of items per page

  defaults to 20

• sort[column]string

  Column to sort by

• sort[direction]string

  Sort direction (asc or desc)

  defaults to asc

Response

200 OKapplication/json

2 fields

• dataarray of objects
  11 fields per item

  • actorUsernamestring
  • citystring
  • countrystring
  • createdAtstring
  • datamap of strings
  • devicestring
  • eventstring
  • idstring
  • ipAddressstring
  • userIDstring
  • usernamestring
• paginationobject
  4 fields

  • currentPageinteger
  • itemsPerPageinteger
  • totalItemsinteger
  • totalPagesinteger

List client names

get/api/audit-logs/filters/client-names

Get a list of all client names for audit log filtering

Response

200 application/json

List users with IDs

get/api/audit-logs/filters/users

Get a list of all usernames with their IDs for audit log filtering

Response

200 application/json

SCIM

SCIM provisioning of an OIDC client.

• post/api/scim/service-providerCreate SCIM service provider
• put/api/scim/service-provider/{id}Update SCIM service provider
• delete/api/scim/service-provider/{id}Delete SCIM service provider
• post/api/scim/service-provider/{id}/syncSync SCIM service provider

Create SCIM service provider

post/api/scim/service-provider

Create a new SCIM service provider

Body application/json

• endpointstringrequired
• oidcClientIdstringrequired
• tokenstring

Response

201 Created SCIM service providerapplication/json

6 fields

• createdAtstring
• endpointstring
• idstring
• lastSyncedAtstring
• oidcClientobject
  8 fields

  • clientTypestring
  • descriptionstring
  • hasDarkLogoboolean
  • hasLogoboolean
  • idstring
  • launchURLstring
  • namestring
  • requiresReauthenticationboolean
• tokenstring

Update SCIM service provider

put/api/scim/service-provider/{id}

Update an existing SCIM service provider

Path parameters

• idstringrequired

  Service Provider ID

Body application/json

• endpointstringrequired
• oidcClientIdstringrequired
• tokenstring

Response

200 Updated SCIM service providerapplication/json

6 fields

• createdAtstring
• endpointstring
• idstring
• lastSyncedAtstring
• oidcClientobject
  8 fields

  • clientTypestring
  • descriptionstring
  • hasDarkLogoboolean
  • hasLogoboolean
  • idstring
  • launchURLstring
  • namestring
  • requiresReauthenticationboolean
• tokenstring

Delete SCIM service provider

delete/api/scim/service-provider/{id}

Delete a SCIM service provider by ID

Path parameters

• idstringrequired

  Service Provider ID

Response

204 No Content

Sync SCIM service provider

post/api/scim/service-provider/{id}/sync

Trigger synchronization for a SCIM service provider

Path parameters

• idstringrequired

  Service Provider ID

Response

200 OK

Device Login

The requests behind sign-in with another device.

• post/api/device-login/requestsCreate device login request
• post/api/device-login/requests/{id}/exchangeExchange device login request
• post/api/device-login/verificationInspect device login request
• post/api/device-login/verification/decisionDecide device login request

Create device login request

post/api/device-login/requests

Create a short-lived request that can be approved from another authenticated device

Response

201 Created device login requestapplication/json

6 fields

• expiresAtstring
• idstring
• intervalinteger
• userCodestring
• verificationUristring
• verificationUriCompletestring

Exchange device login request

post/api/device-login/requests/{id}/exchange

Wait for a device login decision and create a browser session after it has been approved

Path parameters

• idstringrequired

  Device login request ID

Responses

200 Approved request exchanged for a user sessionapplication/json

13 fields

• customClaimsarray of objects
  2 fields per item

  • keystring
  • valuestring
• disabledboolean
• displayNamestring
• emailstring
• emailVerifiedboolean
• firstNamestring
• idstring
• isAdminboolean
• lastNamestring
• ldapIdstring
• localestring
• userGroupsarray of objects
  7 fields per item

  • createdAtstring
  • customClaimsarray of objects
    2 fields per item

    • keystring
    • valuestring
  • friendlyNamestring
  • idstring
  • ldapIdstring
  • namestring
  • userCountinteger
• usernamestring

202 Authorization pending

Inspect device login request

post/api/device-login/verification

Retrieve the requesting device details for an authenticated user before approval or denial

Body application/json

• codestringrequired

Response

200 Device login request detailsapplication/json

6 fields

• citystring
• countrystring
• devicestring
• expiresAtstring
• ipAddressstring
• userCodestring

Decide device login request

post/api/device-login/verification/decision

Approve or deny a device login request; approval requires fresh passkey reauthentication

Body application/json

• codestringrequired
• decisionstringrequired

  One of approve, deny

Response

204 No Content

Well Known

Discovery documents and signing keys, which OIDC clients read without authentication.

• get/.well-known/jwks.jsonGet JSON Web Key Set (JWKS)
• get/.well-known/oauth-authorization-serverGet OAuth 2.0 authorization server metadata
• get/.well-known/openid-configurationGet OpenID Connect discovery configuration

Get JSON Web Key Set (JWKS)

get/.well-known/jwks.json

Returns the JSON Web Key Set used for token verification

Response

200 application/json

Get OAuth 2.0 authorization server metadata

get/.well-known/oauth-authorization-server

Returns the RFC 8414 OAuth 2.0 authorization server metadata document with endpoints and capabilities

Response

200 application/json

Get OpenID Connect discovery configuration

get/.well-known/openid-configuration

Returns the OpenID Connect discovery document with endpoints and capabilities

Response

200 application/json

Version

The running version and the latest release.

• get/api/version/currentGet current deployed version of Pocket ID
• get/api/version/latestGet latest available version of Pocket ID

Get current deployed version of Pocket ID

get/api/version/current

Response

200 application/json

Get latest available version of Pocket ID

get/api/version/latest

Response

200 application/json

Health

A health check for container orchestrators and load balancers.

• get/healthzResponds to healthchecks

Responds to healthchecks

get/healthz

Responds with a successful status code to healthcheck requests

Response

204

Storage

Storage warnings for the admin UI.

• get/api/storage/sqlite-warningGet whether the SQLite storage warning should be shown

Get whether the SQLite storage warning should be shown

get/api/storage/sqlite-warning

Reports whether Pocket ID found its SQLite database on a networked filesystem, which is unsupported and can lead to database corruption

Response

200 application/json