OAuth Grants

The /oauth-grants endpoint manages issued OAuth grants, not OAuth client configuration.

An OAuth grant represents a user's authorization of an OAuth client for a specific combination of:

client
user
account
project
resource
scope set

Internally, grants are derived from refresh token families and associated consent records. The API returns grouped grant records rather than raw refresh token rows.

Typical use cases:

User self-service — list and revoke your own authorized apps
Project admin — review and revoke grants within the current project
Account admin — review and revoke grants across the current account

OAuthGrant Object

Field	Data Type	Description
grant_id	`string`	Synthetic stable identifier derived from client, user, account, project, resource, and scope.
client_id	`string`	OAuth client identifier.
client_name	`string`	Human-readable client name. For CIMD-based clients without a stored `OAuthClient` row, this may fall back to the raw `client_id` value.
user_id	`string`	User ID that granted access.
user_name	`string`	User display name, when available.
user_email	`string`	User email, when available.
account_id	`string`	Account containing the grant.
project_id	`string`	Project containing the grant.
resource	`string`	OAuth resource / audience bound to the issued access token.
scope	`string[]`	Granted scope set.
status	`'active' \| 'revoked' \| 'expired'`	Current grant status derived from the refresh token family.
token_count	`number`	Number of refresh token rows currently associated with the grant family.
granted_at	`string`	ISO 8601 timestamp when consent was granted.
created_at	`string`	ISO 8601 timestamp of the earliest token in the grant family.
last_used_at	`string`	ISO 8601 timestamp of the most recently used refresh token, when available.
expires_at	`string`	ISO 8601 timestamp of the latest token expiry in the grant family, when available.

OAuthGrantRevokeResponse Object

Field	Data Type	Description
revoked_tokens	`number`	Number of refresh token rows revoked by the operation.
revoked_consents	`number`	Number of consent rows revoked by the operation.

OAuthGrantListResponse Object

Field	Data Type	Description
grants	`OAuthGrant[]`	Current page of grants.
total_count	`number`	Total number of matching grants across all pages.
limit	`number`	Page size used for the query.
offset	`number`	Zero-based offset of the current page.

List OAuth Grants

Endpoint: /oauth-grants

Method: GET

Requirements: User must have account:member, project:admin, or account:admin permission. Scope is enforced from the authenticated principal.

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`

Query Parameters

Parameter	Data Type	Description
account_id	`string`	Filter by account. Account admins may only query the current account.
project_id	`string`	Filter by project. Project admins may only query the current project.
user_id	`string`	Filter by user. Non-admin users may only query themselves.
client_id	`string`	Filter by OAuth client ID.
resource	`string`	Filter by OAuth resource / audience.
status	`'active' \| 'revoked' \| 'expired' \| 'all'`	Grant status filter. Defaults to `active`.
limit	`number`	Page size. Defaults to `100`.
offset	`number`	Zero-based offset. Defaults to `0`.
sort_by	`'granted_at' \| 'client_name' \| 'user_name' \| 'resource' \| 'last_used_at' \| 'expires_at' \| 'status'`	Sort field. Defaults to `granted_at`.
sort_order	`'asc' \| 'desc'`	Sort direction. Defaults to `desc`.

Example Response

{
  "grants": [
    {
      "grant_id": "eyJjbGllbnRfaWQiOiJ2dHNfYWJjMTIzIiwidXNlcl9pZCI6IjY3ZTAwMGRkMjEyNWZjNDdlYjllZDgxNSIsImFjY291bnRfaWQiOiI2NTJmZWI4YjM4OTAyYjJlMjI0NWEyZmIiLCJwcm9qZWN0X2lkIjoiNjdkY2YwMjNjMmEwNzYxYjQ0MDUxZjZmIiwicmVzb3VyY2UiOiJodHRwczovL21jcC52ZXJ0ZXNpYS5pby8iLCJzY29wZSI6WyJtY3AiLCJvcGVuaWQiLCJwcm9maWxlIiwicHJvamVjdDo2N2RjZjAyM2MyYTA3NjFiNDQwNTFmNmYiXX0",
      "client_id": "vts_abc123",
      "client_name": "Claude Code",
      "user_id": "67e000dd2125fc47eb9ed815",
      "user_name": "Michael Vachette",
      "user_email": "mvachette@vertesiahq.com",
      "account_id": "652feb8b38902b2e2245a2fb",
      "project_id": "67dcf023c2a0761b44051f6f",
      "resource": "https://mcp.vertesia.io/",
      "scope": ["mcp", "openid", "profile", "project:67dcf023c2a0761b44051f6f"],
      "status": "active",
      "token_count": 1,
      "granted_at": "2026-04-22T07:12:11.000Z",
      "created_at": "2026-04-22T07:12:11.000Z",
      "last_used_at": "2026-04-22T07:13:52.000Z",
      "expires_at": "2026-05-22T07:12:11.000Z"
    }
  ],
  "total_count": 1,
  "limit": 100,
  "offset": 0
}

Code Example

List OAuth Grants

curl --location --request GET 'https://api.vertesia.io/api/v1/oauth-grants?status=active&client_id=vts_abc123&sort_by=granted_at&sort_order=desc&limit=100&offset=0' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>'

Retrieve an OAuth Grant

Endpoint: /oauth-grants/<GRANT_ID>

Method: GET

Requirements: User must have account:member, project:admin, or account:admin permission, and the grant must fall within the caller's accessible scope.

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`

Path Parameters

Parameter	Data Type	Description
`<GRANT_ID>`	`string`	(Required) The synthetic OAuth grant identifier.

Code Example

Retrieve OAuth Grant

curl --location --request GET 'https://api.vertesia.io/api/v1/oauth-grants/<GRANT_ID>' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>'

Revoke One OAuth Grant

Endpoint: /oauth-grants/<GRANT_ID>

Method: DELETE

Requirements: User must have account:member, project:admin, or account:admin permission, and the grant must fall within the caller's accessible scope.

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`

Path Parameters

Parameter	Data Type	Description
`<GRANT_ID>`	`string`	(Required) The synthetic OAuth grant identifier.

Query Parameters

Parameter	Data Type	Description
include_consent	`boolean`	Also revoke the matching consent row. Defaults to `false`.

Example Response

{
  "revoked_tokens": 1,
  "revoked_consents": 0
}

Code Example

Revoke One OAuth Grant

curl --location --request DELETE 'https://api.vertesia.io/api/v1/oauth-grants/<GRANT_ID>?include_consent=true' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>'

Bulk Revoke OAuth Grants

Endpoint: /oauth-grants/revoke

Method: POST

Requirements: User must have account:member, project:admin, or account:admin permission. Scope is enforced from the authenticated principal.

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`
`Content-Type`	`application/json`

Input Parameters

Parameter	Data Type	Description
grant_ids	`string[]`	Explicit list of selected grant IDs to revoke.
account_id	`string`	Filter by account when using filter-based bulk revoke.
project_id	`string`	Filter by project when using filter-based bulk revoke.
user_id	`string`	Filter by user when using filter-based bulk revoke.
client_id	`string`	Filter by OAuth client ID when using filter-based bulk revoke.
resource	`string`	Filter by OAuth resource / audience when using filter-based bulk revoke.
status	`'active' \| 'revoked' \| 'expired' \| 'all'`	Filter by status. Defaults to `active` when filter-based revoke is used.
include_consent	`boolean`	Also revoke matching consent rows. Defaults to `false`.

Notes

If grant_ids is provided, the endpoint revokes exactly those selected grants.
If grant_ids is omitted, the endpoint revokes all grants matching the provided filters.

Example Request: selected rows

{
  "grant_ids": [
    "eyJjbGllbnRfaWQiOiJ2dHNfYWJjMTIzIiwiLi4u",
    "eyJjbGllbnRfaWQiOiJ2dHNfeHl6NDU2IiwiLi4u"
  ],
  "include_consent": true
}

Example Request: filter-based

{
  "user_id": "67e000dd2125fc47eb9ed815",
  "client_id": "vts_abc123",
  "status": "active",
  "include_consent": false
}

Example Response

{
  "revoked_tokens": 4,
  "revoked_consents": 2
}

Code Example

Bulk Revoke OAuth Grants

curl --location --request POST 'https://api.vertesia.io/api/v1/oauth-grants/revoke' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "grant_ids": ["<GRANT_ID_1>", "<GRANT_ID_2>"],
  "include_consent": true
}'