Automate with the Admin API

Get an overview of the OneiD Admin API, how to authenticate to it, what it manages and which administrator roles it respects.

View as Markdown

Everything you can do in the OneiD admin console you can also do through the Admin API. The console itself uses the same API. This page gives an overview; the full description of every operation is in the OpenAPI description on your OneiD instance.

Base path

All Admin API operations live under:

https://YOUR_ONEID/api/admin/v1

Authentication

The Admin API accepts a bearer access token issued by your OneiD deployment.

  • The token must belong to a user who holds an administrator role (see Administrator roles).
  • The token must carry the scope admin_api, or admin_api_readonly for read-only access.
  • Bearer tokens are accepted only under /api.

To get such a token, an administrator with the All role allows admin_api or admin_api_readonly for the client you will use. Only the All role can allow these privileged scopes. Your tool then signs the administrator in with the authorization code flow with PKCE and requests the scope. OneiD removes these scopes at sign-in for users without an administrator role, so a token for an ordinary user never carries them.

Warning Treat a token with admin_api like an administrator password. Do not log it, keep it only as long as the task needs, and use admin_api_readonly when your tool only reads.

What the token can do also depends on the user’s administrator role. A user with a read-only role gets read access only, even with admin_api.

Resources

Resource What you can do
Clients Register, change, enable or disable applications.
Client secrets Set, replace or disable a confidential client’s secret.
Scopes Create and manage API scopes.
Identity resources Manage identity scopes.
Claim types Manage the claim types OneiD knows.
Users Create and change users; assign roles and claims; set account requirements such as a password change or MFA; unlock; reset MFA; reset the password.
Roles Create and manage roles, their users and their claims.
Sessions List active sessions and revoke tokens and authorisations.
Audit Read the audit log.
Signing keys List and rotate signing keys.
Import and export Export and import client definitions.

Example: list clients

GET /api/admin/v1/clients?page=1&pageSize=20 HTTP/1.1
Host: YOUR_ONEID
Authorization: Bearer ADMIN_ACCESS_TOKEN
Accept: application/json

The response is a page of clients (abridged):

{
  "items": [
    {
      "clientId": "orders-web",
      "clientName": "Orders",
      "clientType": "confidential",
      "enabled": true,
      "grantTypes": ["authorization_code", "refresh_token"]
    }
  ],
  "totalCount": 1,
  "page": 1,
  "pageSize": 20
}

OpenAPI description

Your OneiD instance publishes an OpenAPI description of the Admin API at https://YOUR_ONEID/swagger. It is available to signed-in administrators. Use it for the request and response details of every operation.

Administrator roles

OneiD has built-in administrator roles. They decide what a user can do in the admin console and through the Admin API.

Role Meaning
All Full administration. The only role that can manage privileged roles and allow privileged scopes for clients.
AllReadOnly Read everything, change nothing.
UserManager Manage users and roles.
UserManagerReadOnly Read users and roles.
AuthorizationServerManager Manage clients and scopes.
AuthorizationServerManagerReadOnly Read clients and scopes.
Auditer Read the audit log.

Give each administrator the narrowest role that fits their job.

Help-desk webhooks

OneiD accepts two incoming webhooks, so that a help-desk tool can act on a user’s request:

Webhook Effect
POST /api/webhook/v1/reset-password Starts a password reset for a user, who receives a reset email.
POST /api/webhook/v1/reset-mfa Resets a user’s MFA.

The help-desk tool authenticates with a client credentials token that carries the admin_console_webhooks scope. Only an administrator with the All role can allow that scope for a client. The webhooks cannot target administrator accounts. Ask your OneiD operator for the request format.

Not supported OneiD does not send outgoing event webhooks. To follow changes, read the audit log through the Admin API.

Learn more