# 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.

Source: https://oltinid.com/docs/operate/admin-api/ · Section: Operate OneiD · All OneiD documentation: https://oltinid.com/llms.txt

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:

```text
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](#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](https://oltinid.com/docs/guides/authorization-code-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

```http
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):

```json
{
  "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

- [Register an application](https://oltinid.com/docs/get-started/register-an-application/)
- [Client settings](https://oltinid.com/docs/reference/client-settings/)
- [Authorization code flow with PKCE](https://oltinid.com/docs/guides/authorization-code-pkce/)
- [Client credentials for services](https://oltinid.com/docs/guides/client-credentials/)