Admin API reference

GET /admin/whoami

Who is calling

Needs the scope directory or admin.

The caller of this request: a machine (a client with its scopes) or a person signed in to the administration UI.

Responses

• 200 Success
  Body

  Field	Type	Required	Notes
  kind	enum "client" | "user"	yes
  clientId	string	yes
  scopes	array of string	yes
  user	object or null	yes

• 401 unauthorized, 403 forbidden, 429 too many requests: a problem document (application/problem+json)

GET /admin/users

List users

Needs the scope directory or admin.

Newest last. Pass nextCursor as cursor to get the following page.

Parameters

Responses

• 200 Success
  Body

  Field	Type	Required	Notes
  items	array of object	yes
  items[].id	string (uuid)	yes
  items[].email	string	yes
  items[].firstName	string	yes
  items[].lastName	string	yes
  items[].phone	string or null	yes
  items[].phoneVerifiedAt	string or null	yes
  items[].language	string	yes
  items[].status	enum "created" | "active" | "locked" | "deactivated"	yes
  items[].isAdmin	boolean	yes
  items[].lastLoginAt	string or null	yes
  items[].createdAt	string	yes
  items[].updatedAt	string	yes
  nextCursor	string (uuid)	no

• 400 invalid request, 401 unauthorized, 403 forbidden, 404 not found, 409 conflict: a problem document (application/problem+json)

POST /admin/users

Create a user

Needs the scope directory or admin.

Request body

Responses

• 201 Success
  Body

  Field	Type	Required	Notes
  id	string (uuid)	yes
  email	string	yes
  firstName	string	yes
  lastName	string	yes
  phone	string or null	yes
  phoneVerifiedAt	string or null	yes
  language	string	yes
  status	enum "created" | "active" | "locked" | "deactivated"	yes
  isAdmin	boolean	yes
  lastLoginAt	string or null	yes
  createdAt	string	yes
  updatedAt	string	yes

• 400 invalid request, 401 unauthorized, 403 forbidden, 404 not found, 409 conflict: a problem document (application/problem+json)

GET /admin/users/{id}

Get a user

Needs the scope directory or admin.

Parameters

Responses

• 200 Success
  Body

  Field	Type	Required	Notes
  id	string (uuid)	yes
  email	string	yes
  firstName	string	yes
  lastName	string	yes
  phone	string or null	yes
  phoneVerifiedAt	string or null	yes
  language	string	yes
  status	enum "created" | "active" | "locked" | "deactivated"	yes
  isAdmin	boolean	yes
  lastLoginAt	string or null	yes
  createdAt	string	yes
  updatedAt	string	yes

• 400 invalid request, 401 unauthorized, 403 forbidden, 404 not found, 409 conflict: a problem document (application/problem+json)

PATCH /admin/users/{id}

Change a user

Needs the scope directory or admin.

Only the fields given are changed. Nothing is written when nothing differs.

Parameters

Request body

Responses

• 200 Success
  Body

  Field	Type	Required	Notes
  id	string (uuid)	yes
  email	string	yes
  firstName	string	yes
  lastName	string	yes
  phone	string or null	yes
  phoneVerifiedAt	string or null	yes
  language	string	yes
  status	enum "created" | "active" | "locked" | "deactivated"	yes
  isAdmin	boolean	yes
  lastLoginAt	string or null	yes
  createdAt	string	yes
  updatedAt	string	yes

• 400 invalid request, 401 unauthorized, 403 forbidden, 404 not found, 409 conflict: a problem document (application/problem+json)

DELETE /admin/users/{id}

Delete a user

Needs the scope directory or admin.

Removes the user, their claims and devices. The audit log keeps who they were.

Parameters

Responses

• 204 No content
• 400 invalid request, 401 unauthorized, 403 forbidden, 404 not found, 409 conflict: a problem document (application/problem+json)

PUT /admin/users/by-email/{email}

Create or update a user by e-mail

Needs the scope directory or admin.

Idempotent, so an hourly import can call it blindly. Updates names, phone and language; never the password, status or administrator rights. With claims, replaces the values of exactly the claim types given (see PUT /users/{id}/claims). Writes nothing and says unchanged when nothing differs. Everything happens in one transaction: if a claim is invalid, the user is not created or changed either.

With dryRun=true the same checks and the same diff run, then everything is rolled back: nothing is written and no audit event is recorded. The answer says what would happen (created, updated, unchanged) and what would change, so a dry run cannot disagree with the real call.

Parameters

Request body

Responses

• 200 Success
  Body

  Shape 1 of 2

  Field	Type	Required	Notes
  dryRun	enum false	yes
  outcome	enum "updated" | "unchanged"	yes
  user	object	yes
  user.id	string (uuid)	yes
  user.email	string	yes
  user.firstName	string	yes
  user.lastName	string	yes
  user.phone	string or null	yes
  user.phoneVerifiedAt	string or null	yes
  user.language	string	yes
  user.status	enum "created" | "active" | "locked" | "deactivated"	yes
  user.isAdmin	boolean	yes
  user.lastLoginAt	string or null	yes
  user.createdAt	string	yes
  user.updatedAt	string	yes
  claims	map of array of string	yes

  Shape 2 of 2

  Field	Type	Required	Notes
  dryRun	enum true	yes
  outcome	enum "created" | "updated" | "unchanged"	yes
  changes	object	yes
  changes.profile	map of object	yes
  changes.claims	map of object	yes

• 201 Success
  Body

  Field	Type	Required	Notes
  dryRun	enum false	yes
  outcome	enum "created"	yes
  user	object	yes
  user.id	string (uuid)	yes
  user.email	string	yes
  user.firstName	string	yes
  user.lastName	string	yes
  user.phone	string or null	yes
  user.phoneVerifiedAt	string or null	yes
  user.language	string	yes
  user.status	enum "created" | "active" | "locked" | "deactivated"	yes
  user.isAdmin	boolean	yes
  user.lastLoginAt	string or null	yes
  user.createdAt	string	yes
  user.updatedAt	string	yes
  claims	map of array of string	yes

• 400 invalid request, 401 unauthorized, 403 forbidden, 404 not found, 409 conflict: a problem document (application/problem+json)

GET /admin/users/{id}/sessions

Where a user is signed in

Needs the scope directory or admin.

The browser sessions (single sign-on) that are open, and the applications that were granted access and stay signed in, such as an app on a phone. Identifiers and tokens are not returned. POST /users/{id}/end-sessions ends them all.

Parameters

Responses

• 200 Success
  Body

  Field	Type	Required	Notes
  sessions	array of object	yes
  sessions[].startedAt	string	yes
  sessions[].expiresAt	string or null	yes
  sessions[].acr	string or null	yes
  sessions[].applications	array of object	yes
  sessions[].applications[].clientId	string	yes
  sessions[].applications[].name	string	yes
  grants	array of object	yes
  grants[].clientId	string	yes
  grants[].name	string	yes
  grants[].since	string	yes
  grants[].expiresAt	string or null	yes

• 400 invalid request, 401 unauthorized, 403 forbidden, 404 not found, 429 too many requests: a problem document (application/problem+json)

POST /admin/users/{id}/lock

Lock a user

Needs the scope directory or admin.

For a created or active user. Ends all their sessions and refresh tokens; they cannot sign in until unlocked.

Parameters

Responses

• 200 Success
  Body

  Field	Type	Required	Notes
  id	string (uuid)	yes
  email	string	yes
  firstName	string	yes
  lastName	string	yes
  phone	string or null	yes
  phoneVerifiedAt	string or null	yes
  language	string	yes
  status	enum "created" | "active" | "locked" | "deactivated"	yes
  isAdmin	boolean	yes
  lastLoginAt	string or null	yes
  createdAt	string	yes
  updatedAt	string	yes

• 400 invalid request, 401 unauthorized, 403 forbidden, 404 not found, 409 conflict, 429 too many requests, 503 unavailable: a problem document (application/problem+json)

POST /admin/users/{id}/unlock

Unlock a user

Needs the scope directory or admin.

For a locked user: they become active again, or created if they never set a password. For an active user, who is not locked, nothing changes except that the failed sign-in attempts held against their address are forgotten, so they can try again at once after too many mistakes.

Parameters

Responses

• 200 Success
  Body

  Field	Type	Required	Notes
  id	string (uuid)	yes
  email	string	yes
  firstName	string	yes
  lastName	string	yes
  phone	string or null	yes
  phoneVerifiedAt	string or null	yes
  language	string	yes
  status	enum "created" | "active" | "locked" | "deactivated"	yes
  isAdmin	boolean	yes
  lastLoginAt	string or null	yes
  createdAt	string	yes
  updatedAt	string	yes

• 400 invalid request, 401 unauthorized, 403 forbidden, 404 not found, 409 conflict, 429 too many requests, 503 unavailable: a problem document (application/problem+json)

POST /admin/users/{id}/deactivate

Deactivate a user

Needs the scope directory or admin.

For someone who has left. Ends all sessions and refresh tokens and cancels a pending activation link.

Parameters

Responses

• 200 Success
  Body

  Field	Type	Required	Notes
  id	string (uuid)	yes
  email	string	yes
  firstName	string	yes
  lastName	string	yes
  phone	string or null	yes
  phoneVerifiedAt	string or null	yes
  language	string	yes
  status	enum "created" | "active" | "locked" | "deactivated"	yes
  isAdmin	boolean	yes
  lastLoginAt	string or null	yes
  createdAt	string	yes
  updatedAt	string	yes

• 400 invalid request, 401 unauthorized, 403 forbidden, 404 not found, 409 conflict, 429 too many requests, 503 unavailable: a problem document (application/problem+json)

POST /admin/users/{id}/activate

Activate a user

Needs the scope directory or admin.

For a created user: sends the activation link, where they choose their first password; a new call replaces the earlier link. For a deactivated user who already has a password: makes them active again, without a link. The link is never returned or logged by pforte.

Parameters

Responses

• 200 Success
  Body

  Field	Type	Required	Notes
  user	object	yes
  user.id	string (uuid)	yes
  user.email	string	yes
  user.firstName	string	yes
  user.lastName	string	yes
  user.phone	string or null	yes
  user.phoneVerifiedAt	string or null	yes
  user.language	string	yes
  user.status	enum "created" | "active" | "locked" | "deactivated"	yes
  user.isAdmin	boolean	yes
  user.lastLoginAt	string or null	yes
  user.createdAt	string	yes
  user.updatedAt	string	yes
  activation	object	yes
  activation.linkSent	boolean	yes
  activation.expiresAt	string or null	yes

• 400 invalid request, 401 unauthorized, 403 forbidden, 404 not found, 409 conflict, 429 too many requests, 503 unavailable: a problem document (application/problem+json)

POST /admin/users/{id}/reset-password

Reset the password of a user

Needs the scope directory or admin.

For an active user. Sends them a code to choose a new password and ends all their sessions and refresh tokens, since the account may be compromised.

Parameters

Responses

• 200 Success
  Body

  Field	Type	Required	Notes
  id	string (uuid)	yes
  email	string	yes
  firstName	string	yes
  lastName	string	yes
  phone	string or null	yes
  phoneVerifiedAt	string or null	yes
  language	string	yes
  status	enum "created" | "active" | "locked" | "deactivated"	yes
  isAdmin	boolean	yes
  lastLoginAt	string or null	yes
  createdAt	string	yes
  updatedAt	string	yes

• 400 invalid request, 401 unauthorized, 403 forbidden, 404 not found, 409 conflict, 429 too many requests, 503 unavailable: a problem document (application/problem+json)

POST /admin/users/{id}/end-sessions

End all sessions of a user

Needs the scope directory or admin.

Deletes their sessions, grants and refresh tokens and revokes their remembered devices, so they must sign in again, with a code. Their status does not change.

Parameters

Responses

• 200 Success
  Body

  Field	Type	Required	Notes
  sessionsEnded	integer	yes	-9007199254740991 to 9007199254740991
  devicesRevoked	integer	yes	-9007199254740991 to 9007199254740991

• 400 invalid request, 401 unauthorized, 403 forbidden, 404 not found, 409 conflict, 429 too many requests, 503 unavailable: a problem document (application/problem+json)

GET /admin/users/{id}/devices

List the remembered devices of a user

Needs the scope directory or admin.

Devices that skip the second factor: not revoked and not expired. Most recently seen first.

Parameters

Responses

• 200 Success
  Body

  Field	Type	Required	Notes
  items	array of object	yes
  items[].id	string (uuid)	yes
  items[].userAgent	string or null	yes
  items[].createdAt	string	yes
  items[].lastSeenAt	string	yes
  items[].expiresAt	string	yes

• 400 invalid request, 401 unauthorized, 403 forbidden, 404 not found: a problem document (application/problem+json)

DELETE /admin/users/{id}/devices

Revoke all remembered devices of a user

Needs the scope directory or admin.

Every sign-in of the user asks for the code again. Locking, deactivating, resetting the password and ending sessions do this as well.

Parameters

Responses

• 200 Success
  Body

  Field	Type	Required	Notes
  devicesRevoked	integer	yes	-9007199254740991 to 9007199254740991

• 400 invalid request, 401 unauthorized, 403 forbidden, 404 not found: a problem document (application/problem+json)

DELETE /admin/users/{id}/devices/{deviceId}

Revoke a remembered device

Needs the scope directory or admin.

The next sign-in on that device asks for the code again.

Parameters

Responses

• 204 No content
• 400 invalid request, 401 unauthorized, 403 forbidden, 404 not found: a problem document (application/problem+json)

GET /admin/users/{id}/claims

The claim values of a user

Needs the scope directory or admin.

Parameters

Responses

• 200 Success
  Body

  Field	Type	Required	Notes
  claims	map of array of string	yes

• 400 invalid request, 401 unauthorized, 403 forbidden, 404 not found, 409 conflict: a problem document (application/problem+json)

PUT /admin/users/{id}/claims

Set claims in bulk

Needs the scope directory or admin.

Replaces the values of exactly the claim types given and leaves every other claim of the user untouched. An empty list removes all values of a type. All values are checked first; if any is invalid nothing is changed.

Parameters

Request body

Responses

• 200 Success
  Body

  Field	Type	Required	Notes
  changed	boolean	yes
  claims	map of array of string	yes

• 400 invalid request, 401 unauthorized, 403 forbidden, 404 not found, 409 conflict: a problem document (application/problem+json)

POST /admin/users/{id}/claims/{type}

Add one value to a claim type

Needs the scope directory or admin.

Does nothing if the user already has the value. A single-valued type refuses a second, different value.

Parameters

Request body

Responses

• 200 Success
  Body

  Field	Type	Required	Notes
  changed	boolean	yes
  claims	map of array of string	yes

• 400 invalid request, 401 unauthorized, 403 forbidden, 404 not found, 409 conflict: a problem document (application/problem+json)

PUT /admin/users/{id}/claims/{type}

Set the values of one claim type

Needs the scope directory or admin.

Parameters

Request body

Responses

• 200 Success
  Body

  Field	Type	Required	Notes
  changed	boolean	yes
  claims	map of array of string	yes

• 400 invalid request, 401 unauthorized, 403 forbidden, 404 not found, 409 conflict: a problem document (application/problem+json)

DELETE /admin/users/{id}/claims/{type}/{value}

Remove one value of a claim type

Needs the scope directory or admin.

Does nothing if the user does not have the value.

Parameters

Responses

• 200 Success
  Body

  Field	Type	Required	Notes
  changed	boolean	yes
  claims	map of array of string	yes

• 400 invalid request, 401 unauthorized, 403 forbidden, 404 not found, 409 conflict: a problem document (application/problem+json)

GET /admin/claim-types

List claim types

Needs the scope directory or admin.

Responses

• 200 Success
  Body

  Field	Type	Required	Notes
  items	array of object	yes
  items[].key	string	yes
  items[].description	string	yes
  items[].valuePattern	string or null	yes
  items[].multiValued	boolean	yes
  items[].clients	array of string	yes

• 400 invalid request, 401 unauthorized, 403 forbidden, 404 not found, 409 conflict: a problem document (application/problem+json)

POST /admin/claim-types

Create a claim type

Needs the scope admin.

The key is the claim name in tokens. Names that tokens already use (email, name, …) are reserved.

Request body

Responses

• 201 Success
  Body

  Field	Type	Required	Notes
  key	string	yes
  description	string	yes
  valuePattern	string or null	yes
  multiValued	boolean	yes
  clients	array of string	yes

• 400 invalid request, 401 unauthorized, 403 forbidden, 404 not found, 409 conflict: a problem document (application/problem+json)

PATCH /admin/claim-types/{key}

Change a claim type

Needs the scope admin.

Refused with 409 when existing values would violate the change: a new pattern they do not match, or single-valued while a user holds several values.

Parameters

Request body

Responses

• 200 Success
  Body

  Field	Type	Required	Notes
  key	string	yes
  description	string	yes
  valuePattern	string or null	yes
  multiValued	boolean	yes
  clients	array of string	yes

• 400 invalid request, 401 unauthorized, 403 forbidden, 404 not found, 409 conflict: a problem document (application/problem+json)

DELETE /admin/claim-types/{key}

Delete a claim type

Needs the scope admin.

Refused with 409 while users hold values of it. With force=true the values are deleted too, and the audit log records how many users and values were affected.

Parameters

Responses

• 204 No content
• 400 invalid request, 401 unauthorized, 403 forbidden, 404 not found, 409 conflict: a problem document (application/problem+json)

GET /admin/clients/{clientId}/claim-types

The claim types a client receives

Needs the scope admin.

Parameters

Responses

• 200 Success
  Body

  Field	Type	Required	Notes
  claimTypes	array of string	yes

• 400 invalid request, 401 unauthorized, 403 forbidden, 404 not found, 409 conflict: a problem document (application/problem+json)

PUT /admin/clients/{clientId}/claim-types

Set the claim types a client receives

Needs the scope admin.

Replaces the whole set. A client only ever receives the claim types assigned to it.

Parameters

Request body

Responses

• 200 Success
  Body

  Field	Type	Required	Notes
  claimTypes	array of string	yes

• 400 invalid request, 401 unauthorized, 403 forbidden, 404 not found, 409 conflict: a problem document (application/problem+json)

GET /admin/clients

List clients

Needs the scope admin.

Responses

• 200 Success
  Body

  Field	Type	Required	Notes
  items	array of object	yes
  items[].system	boolean	yes
  items[].clientId	string	yes
  items[].name	string	yes
  items[].type	enum "public" | "confidential"	yes
  items[].redirectUris	array of string	yes
  items[].postLogoutRedirectUris	array of string	yes
  items[].backchannelLogoutUri	string or null	yes
  items[].backchannelLogoutSessionRequired	boolean	yes
  items[].allowedGrants	array of string	yes
  items[].scopes	array of string	yes
  items[].pkceRequired	boolean	yes
  items[].claimTypes	array of string	yes
  items[].createdAt	string	yes
  items[].updatedAt	string	yes

• 400 invalid request, 401 unauthorized, 403 forbidden, 404 not found, 409 conflict: a problem document (application/problem+json)

POST /admin/clients

Register a client

Needs the scope admin.

Two kinds exist. An application signs users in (authorization code flow, public or confidential) and has OpenID scopes and redirect URIs. A machine calls the admin API with the client_credentials grant and has only the scopes admin and/or directory. They never mix. A confidential client gets a generated secret, returned here once and never again. Redirect URIs must be https (http only for localhost).

Request body

Responses

• 201 Success
  Body

  Field	Type	Required	Notes
  client	object	yes
  client.system	boolean	yes
  client.clientId	string	yes
  client.name	string	yes
  client.type	enum "public" | "confidential"	yes
  client.redirectUris	array of string	yes
  client.postLogoutRedirectUris	array of string	yes
  client.backchannelLogoutUri	string or null	yes
  client.backchannelLogoutSessionRequired	boolean	yes
  client.allowedGrants	array of string	yes
  client.scopes	array of string	yes
  client.pkceRequired	boolean	yes
  client.claimTypes	array of string	yes
  client.createdAt	string	yes
  client.updatedAt	string	yes
  clientSecret	string or null	yes

• 400 invalid request, 401 unauthorized, 403 forbidden, 404 not found, 409 conflict: a problem document (application/problem+json)

GET /admin/clients/{clientId}

Get a client

Needs the scope admin.

Parameters

Responses

• 200 Success
  Body

  Field	Type	Required	Notes
  system	boolean	yes
  clientId	string	yes
  name	string	yes
  type	enum "public" | "confidential"	yes
  redirectUris	array of string	yes
  postLogoutRedirectUris	array of string	yes
  backchannelLogoutUri	string or null	yes
  backchannelLogoutSessionRequired	boolean	yes
  allowedGrants	array of string	yes
  scopes	array of string	yes
  pkceRequired	boolean	yes
  claimTypes	array of string	yes
  createdAt	string	yes
  updatedAt	string	yes

• 400 invalid request, 401 unauthorized, 403 forbidden, 404 not found, 409 conflict: a problem document (application/problem+json)

PATCH /admin/clients/{clientId}

Change a client

Needs the scope admin.

Only the fields given are changed, and the result must still be a valid client of its kind. Takes effect at once. The last client with the admin scope cannot lose it.

Parameters

Request body

Responses

• 200 Success
  Body

  Field	Type	Required	Notes
  system	boolean	yes
  clientId	string	yes
  name	string	yes
  type	enum "public" | "confidential"	yes
  redirectUris	array of string	yes
  postLogoutRedirectUris	array of string	yes
  backchannelLogoutUri	string or null	yes
  backchannelLogoutSessionRequired	boolean	yes
  allowedGrants	array of string	yes
  scopes	array of string	yes
  pkceRequired	boolean	yes
  claimTypes	array of string	yes
  createdAt	string	yes
  updatedAt	string	yes

• 400 invalid request, 401 unauthorized, 403 forbidden, 404 not found, 409 conflict: a problem document (application/problem+json)

DELETE /admin/clients/{clientId}

Delete a client

Needs the scope admin.

Also removes its claim type assignments and revokes every grant and token issued to it. Refused for the last client with the admin scope and for the client making the call.

Parameters

Responses

• 204 No content
• 400 invalid request, 401 unauthorized, 403 forbidden, 404 not found, 409 conflict: a problem document (application/problem+json)

POST /admin/clients/{clientId}/rotate-secret

Replace the secret of a confidential client

Needs the scope admin.

The old secret stops working at once. The new one is returned here once and never again.

Parameters

Responses

• 200 Success
  Body

  Field	Type	Required	Notes
  clientSecret	string	yes

• 400 invalid request, 401 unauthorized, 403 forbidden, 404 not found, 409 conflict: a problem document (application/problem+json)

GET /admin/audit-events

List audit events

Needs the scope admin.

Newest first. Every change through the admin API and every lifecycle action is recorded with the client that made it. Pass nextCursor as cursor to get older events; the order is stable while new events arrive.

Parameters

Responses

• 200 Success
  Body

  Field	Type	Required	Notes
  items	array of object	yes
  items[].id	string (uuid)	yes
  items[].createdAt	string	yes
  items[].actorType	enum "user" | "client" | "system"	yes
  items[].actorId	string or null	yes
  items[].action	string	yes
  items[].targetType	string or null	yes
  items[].targetId	string or null	yes
  items[].details	map of any	yes
  items[].ip	string or null	yes
  items[].userAgent	string or null	yes
  nextCursor	string (uuid)	no

• 400 invalid request, 401 unauthorized, 403 forbidden: a problem document (application/problem+json)