OAuth Client Administration

OAuth clients are service accounts that authenticate via the OAuth 2.0 client_credentials grant. Each client has a client_id, a client_secret (stored as a SHA-256 hash — never retrievable after creation), an assigned scope set, and a rate limit tier.

This guide covers client lifecycle management from the admin console and via the admin API. For the M2M token flow itself, see OAuth 2.0 M2M API.

Admin API reference

All endpoints require an admin session or an M2M token with admin:write scope.

Base path: /api/v1/admin/oauth-clients

Method	Path	Description
`POST`	`/api/v1/admin/oauth-clients/`	Create a new client
`GET`	`/api/v1/admin/oauth-clients/`	List clients (paginated)
`GET`	`/api/v1/admin/oauth-clients/{client_id}`	Get a single client
`PUT`	`/api/v1/admin/oauth-clients/{client_id}`	Update client settings
`DELETE`	`/api/v1/admin/oauth-clients/{client_id}`	Delete (revoke) a client

Creating a client

POST /api/v1/admin/oauth-clients/
Content-Type: application/json

{
  "name": "SIEM Export Service",
  "scopes": ["audit:read"],
  "rate_limit_tier": "standard",
  "token_lifetime_seconds": 3600
}

Field	Type	Required	Default	Description
`name`	string	Yes	—	Human-readable display name (1–255 chars)
`scopes`	string[]	No	`[]`	Scope strings granted to this client
`tenant_id`	UUID	No	null	Tenant/org UUID for multi-tenant isolation. Null for platform-wide clients.
`rate_limit_tier`	string	No	`"standard"`	Rate limit policy: `standard`, `premium`, or `unlimited`
`token_lifetime_seconds`	int	No	`3600`	Access token TTL in seconds. Range: 1–86400 (24 hours).

Response — 201 Created

{
  "id": "a1b2c3d4-...",
  "client_id": "e5f6a7b8-...",
  "client_secret": "arb1_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "name": "SIEM Export Service",
  "scopes": ["audit:read"],
  "tenant_id": null,
  "created_by": "admin-user-uuid",
  "enabled": true,
  "rate_limit_tier": "standard",
  "token_lifetime_seconds": 3600,
  "created_at": "2026-03-12T12:00:00Z",
  "last_used": null
}

Listing clients

GET /api/v1/admin/oauth-clients/?limit=50&offset=0

Returns a list of client records (newest first). No client_secret is returned.

Parameter	Type	Default	Description
`limit`	int	`50`	Records per page (1–500)
`offset`	int	`0`	Number of records to skip

Getting a single client

GET /api/v1/admin/oauth-clients/{client_id}

Returns a single OAuthClientResponse object. The client_id path parameter is the public client UUID (the client_id field, not the internal id).

Updating a client

PUT /api/v1/admin/oauth-clients/{client_id}
Content-Type: application/json

All fields are optional — only the fields you send are updated.

{
  "name": "SIEM Export Service v2",
  "scopes": ["audit:read", "api:read"],
  "enabled": true,
  "rate_limit_tier": "premium",
  "token_lifetime_seconds": 7200
}

Field	Type	Description
`name`	string	Display name
`scopes`	string[]	Full scope list (replaces existing)
`enabled`	bool	Enable or disable the client
`rate_limit_tier`	string	`standard`, `premium`, or `unlimited`
`token_lifetime_seconds`	int	Token TTL (1–86400 seconds)

Updating scopes replaces the entire scope list. To add a scope, include all existing scopes plus the new one.

Disabling a client

To temporarily suspend access without losing the client registration, set enabled to false:

PUT /api/v1/admin/oauth-clients/{client_id}
Content-Type: application/json

{"enabled": false}

A disabled client receives a 401 invalid_client error when attempting to obtain tokens. Re-enable by setting enabled: true.

Rotating a client secret

There is no dedicated rotation endpoint. To rotate a client secret:

Delete the existing client (DELETE /api/v1/admin/oauth-clients/{client_id}).
Create a new client with the same settings (POST /api/v1/admin/oauth-clients/).
Update any services using the old credentials with the new client_id and client_secret.

Deletion immediately invalidates all outstanding tokens issued for that client. There is no grace period.

Deleting (revoking) a client

DELETE /api/v1/admin/oauth-clients/{client_id}

Returns 204 No Content on success. Permanently removes the client record and invalidates all outstanding tokens. This action is not reversible.

Scope reference

Assign scopes based on what the client application needs to access. Use the minimum set required.

Scope	API access
`api:read`	Read access to core API endpoints
`api:write`	Write access to core API endpoints
`admin:read`	Read access to admin endpoints
`admin:write`	Write access to admin endpoints (includes client management)
`audit:read`	Audit log search and export
`dlp:read`	DLP rule and result endpoints

Rate limit tiers

Tier	Description
`standard`	Default. Suitable for most service accounts.
`premium`	Higher per-minute request limits for high-throughput integrations.
`unlimited`	No rate limiting applied. Use for trusted internal services only.

The rate_limit_tier value is embedded in each issued JWT (rate_limit_tier claim) and enforced by the platform rate limit middleware. See Rate limiting for per-tier limits.

Token lifetime

token_lifetime_seconds controls how long issued access tokens are valid:

Minimum: 1 second
Maximum: 86400 seconds (24 hours)
Default: 3600 seconds (1 hour)

The effective lifetime is capped at 86400 regardless of the configured value. Short-lived tokens reduce the exposure window if a token is compromised. Use the shortest lifetime your client’s token refresh logic supports.

Admin console walkthrough

The OAuth Clients panel in the admin console (/admin/oauth-clients) provides a table view of all registered clients, with inline actions:

Create — Opens a modal to set name, scopes (checkboxes), rate limit tier, and token lifetime.
Enable / Disable — Toggles the enabled field without deleting the record.
Revoke — Permanently deletes the client and its outstanding tokens (confirmation required).

The client_secret reveal panel displays the plaintext secret immediately after creation, with a clipboard copy button. This panel is shown only once — closing it dismisses the secret permanently.

The Last used column tracks the most recent successful token issuance timestamp (last_used field). A — value indicates the client has never successfully authenticated.