> For the complete documentation index, see [llms.txt](https://docs.contextual.io/documentation-and-resources/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.contextual.io/documentation-and-resources/tenants/tenant-apis/auth-administration-api.md).

# Auth Administration API

Check your API Key's permissions and understand the API behind tenant access management in the Admin Console.

The Auth Administration API powers tenant access management in the Admin Console, including team members, invitations, Roles, and API Keys. Your solution code can also use it to check the identity and permissions of its API Key, for example when troubleshooting a `403` response from another Tenant API.

## What you can do

Use `GET /me` to check the calling credential's identity and `GET /me/permissions` to check its permissions in the tenant.

The Admin Console uses this API to:

* List team members, change the Roles assigned to a member, and remove a member from the tenant. People join only by accepting an invitation, and each member needs at least one Role.
* Invite a person by email address with one or more Roles, and list or revoke pending invitations. The person accepts the invitation by signing in with that email address.
* Create, change, and delete Roles and the permissions they grant.
* Create, change, disable, and delete API Keys. Set an API Key's permissions, and read or rotate its Client Secret.
* Look up the tenant's API Identifiers. You use an API Identifier as the `audience` when you request an access token.

## Base URL and reference

* **API base URL:** `https://auth.<tenant-id>.my.contextual.io/api/v1`
* **Swagger reference:** [Auth Administration API reference](https://auth.prod-001.prod.contextual.io/api-docs/)
* **Raw OpenAPI:** [openapi.json](https://auth.prod-001.prod.contextual.io/api-docs/openapi.json)

The reference is titled **Contextual Auth API** and includes the operations used by the Admin Console.

Replace `<tenant-id>` with the [tenant ID from your Tenant Workspace URL](https://docs.contextual.io/documentation-and-resources/tenants/tenant-apis/authentication-and-permissions.md#identify-the-tenant). On the API base URL, the hostname identifies your tenant.

Most operations have two equivalent paths. One includes the tenant ID, such as `/organizations/<tenant-id>/roles`. The other omits it, such as `/roles`. Both work on the API base URL. If the path or an `x-org-id` header also names the tenant, every value must match. Otherwise the API returns `400`.

The OpenAPI document uses the relative server `/api/v1`. When you import it into an API client or AI tool, set the server to the API base URL.

## Authentication and permissions

To call `GET /me` or `GET /me/permissions` with an API Key, follow [Get and use an access token](https://docs.contextual.io/documentation-and-resources/tenants/tenant-apis/authentication-and-permissions.md#get-and-use-an-access-token), then send the token in the `Authorization: Bearer <access-token>` header.

`GET /me` and `GET /me/permissions` work for any caller in the tenant, including an API Key. They need no specific permission.

When you manage tenant access in the Admin Console, the API checks your Role permissions. Accepting an invitation uses the invited person's sign-in. The table below maps the Console's Role permissions to the scopes shown in the reference.

| Area                   | Role permission in the Admin Console | Scopes shown in the reference          |
| ---------------------- | ------------------------------------ | -------------------------------------- |
| Team members           | **Tenant security → Team members**   | `contextual:users:<action>`            |
| Invitations            | **Tenant security → Invitations**    | `contextual:invitations:<action>`      |
| Roles                  | **Tenant security → Roles**          | `contextual:roles:<action>`            |
| API Keys               | **Tenant API → Clients**             | `contextual:clients:<action>`          |
| API Key Client Secrets | **Tenant API → Client secrets**      | `contextual:client-secrets:<action>`   |
| API Key permissions    | **Tenant API → Client grants**       | `contextual:client-grants:<action>`    |
| API Identifiers        | **Tenant API → Resource servers**    | `contextual:resource-servers:<action>` |

For the listed Console operations, reading and listing need `read`. Creating needs `create`, changing needs `update`, and deleting or removing needs `delete`. Reading a Client Secret needs `read` on client secrets, and rotating it needs `update`. Deleting an API Key needs `delete` on both clients and client grants. The reference lists the required scopes for each operation. For the Role permissions that each API Key task in the Admin Console needs, see [Permissions for each task](https://docs.contextual.io/documentation-and-resources/tenants/tenant-apis/authentication-and-permissions.md#permissions-for-each-task).

These permissions control who can access your tenant and what they can do. Grant them only to trusted administrators.

## Request and response details

* Request and response bodies are JSON.
* List responses return results in `items`. To get the next page, send the returned `nextPageToken` as `pageToken`. Continue until a response has no `nextPageToken`, even if `items` is empty. Use `pageSize` to set the page size. To get `totalCount`, add `includeTotal=true` to a request without `pageToken`.
* If a request fails because the caller lacks a permission, the `403` response has `code` set to `invalid_permissions`. Its `errors[0].requiredPermissions` lists the permissions that the operation requires. Other `403` responses do not include this field.

## Example request

This request lists the permissions of the token you send:

```bash
curl "https://auth.<tenant-id>.my.contextual.io/api/v1/me/permissions" \
  --header "Authorization: Bearer <access-token>"
```

Replace `<access-token>` with your access token. A successful response has status `200` and lists the caller's permissions in `permissions`. Use it to check what a token can do, for example when another Tenant API returns `403`. After a permission change, another API can take up to about five minutes to apply it, even when this request already shows the change.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.contextual.io/documentation-and-resources/tenants/tenant-apis/auth-administration-api.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
