> ## Documentation Index > Fetch the complete documentation index at: https://www.1password.dev/llms.txt > Use this file to discover all available pages before exploring further. # Introspect an access token > Check whether an OAuth 2.0 access token for the 1Password Users API is active and retrieve its scopes and expiry time. Check whether an access token is still active and retrieve its metadata, such as its scopes and expiry time, before you use it. Authenticate with the client credentials of the OAuth application the token was issued to. The response returns `200 OK` for an active token. If a token has expired, been revoked, is unknown, or was issued to a different OAuth application, the response also returns `200 OK`, but with `"active": false` and no other fields, so the response doesn't reveal anything about tokens that don't belong to your application. If the `token` parameter isn't included in the request, the response returns a `400 Bad Request` error. This endpoint is rate limited. Requests that exceed the limit return a `429 Too Many Requests` error. Learn more about [errors](/users-api/conventions#errors) and [rate limits](/users-api/conventions#rate-limits). ## OpenAPI ````yaml openapi/oauth_api.yaml POST /v1/oauth/introspect openapi: 3.1.0 info: title: 1Password OAuth API version: v1 description: >- The 1Password OAuth API issues, inspects, and revokes the OAuth 2.0 access tokens used to authorize requests to the 1Password Users API. Integrations authenticate with the client ID and client secret of an OAuth application in a 1Password account, using the OAuth 2.0 client credentials grant (RFC 6749 §4.4). Access tokens are opaque bearer tokens that expire after 15 minutes and carry the scopes configured for the OAuth application. Tokens can be revoked before they expire (RFC 7009) and checked with token introspection (RFC 7662). Refresh tokens aren't issued for the client credentials grant; request a new access token when the current one expires. All requests use `Content-Type: application/x-www-form-urlencoded`. Responses that return a body are JSON and include `Cache-Control: no-store` and `Pragma: no-cache`, so tokens are never cached. A successful revocation returns an empty `200 OK` response. contact: name: 1Password url: https://1password.com/contact-us servers: - url: https://api.1password.com description: 1Password.com (United States) - url: https://api.1password.ca description: 1Password.ca (Canada) - url: https://api.1password.eu description: 1Password.eu (Europe) - url: https://api.ent.1password.com description: ent.1password.com security: [] tags: - name: OAuth tokens description: Request, introspect, and revoke OAuth 2.0 access tokens for the Users API. x-group: OAuth tokens paths: /v1/oauth/introspect: post: tags: - OAuth tokens summary: Introspect an access token description: >- Check whether an access token is active and retrieve its metadata, following RFC 7662. Authenticate with the client credentials of the OAuth application that the token was issued to, using HTTP Basic authentication or the `client_id` and `client_secret` form fields. The response always returns `200 OK`. An active token returns `"active": true` with its scopes, client ID, and issue and expiry times. A token that is expired, revoked, unknown, or issued to a different OAuth application returns `"active": false` with no other fields. Requests to this endpoint share the token endpoint's rate limits. operationId: introspectAccessToken requestBody: required: true content: application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/IntrospectRequest' example: token: >- op_o_c_H3WVOKGN4B7JXQYCQ6DJFAW5ZU_Q2s4ZmVnaGprbG1ub3BxcnN0dXZ3eHl6MDEyMzQ1Njc4OWFi responses: '200': description: The token's introspection result. headers: Cache-Control: $ref: '#/components/headers/CacheControl' Pragma: $ref: '#/components/headers/Pragma' content: application/json: schema: $ref: '#/components/schemas/IntrospectionResponse' examples: active: summary: Active token value: active: true scope: users.view users.suspend users.reactivate client_id: H3WVOKGN4B7JXQYCQ6DJFAW5ZU sub: H3WVOKGN4B7JXQYCQ6DJFAW5ZU token_type: Bearer exp: 1760000900 iat: 1760000000 inactive: summary: Expired, revoked, unknown, or another application's token value: active: false '400': description: Bad Request - The `token` parameter is missing. content: application/json: schema: $ref: '#/components/schemas/OAuthError' example: error: invalid_request error_description: 'missing required parameter: token' '401': description: Unauthorized - Client credentials are missing or invalid. headers: WWW-Authenticate: description: Returned when the request used Basic authentication. schema: type: string example: Basic realm="introspect" content: application/json: schema: $ref: '#/components/schemas/OAuthError' example: error: invalid_client error_description: client authentication failed '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/Internal' '503': $ref: '#/components/responses/Unavailable' security: - BasicAuth: [] components: schemas: IntrospectRequest: allOf: - $ref: '#/components/schemas/ClientCredentialsFields' - type: object required: - token properties: token: type: string description: The access token to introspect. token_type_hint: type: string enum: - access_token description: >- A hint about the type of token. Optional; only access tokens are issued. IntrospectionResponse: type: object required: - active properties: active: type: boolean description: >- Whether the token is currently active. `false` for tokens that are expired, revoked, unknown, or issued to a different OAuth application; the remaining fields are omitted in that case. scope: type: string description: The scopes granted to the token, separated by spaces. example: users.view users.suspend users.reactivate client_id: type: string description: The client ID of the OAuth application the token was issued to. example: H3WVOKGN4B7JXQYCQ6DJFAW5ZU sub: type: string description: >- The subject of the token. For client credentials tokens, this is the client ID. example: H3WVOKGN4B7JXQYCQ6DJFAW5ZU token_type: type: string description: The token type. Always `Bearer` for active tokens. example: Bearer exp: type: integer format: int64 description: When the token expires, as a Unix timestamp in seconds. example: 1760000900 iat: type: integer format: int64 description: When the token was issued, as a Unix timestamp in seconds. example: 1760000000 additionalProperties: false OAuthError: type: object description: An OAuth 2.0 error response (RFC 6749 §5.2). required: - error properties: error: type: string enum: - invalid_request - invalid_client - unauthorized_client - unsupported_grant_type - unauthorized - slow_down - server_error description: A machine-readable error code. error_description: type: string description: A human-readable description of the error. additionalProperties: false ClientCredentialsFields: type: object properties: client_id: type: string description: >- The client ID of the OAuth application. Use together with `client_secret` as an alternative to HTTP Basic authentication. example: H3WVOKGN4B7JXQYCQ6DJFAW5ZU client_secret: type: string description: >- The client secret of the OAuth application. Use together with `client_id` as an alternative to HTTP Basic authentication. headers: CacheControl: description: Always `no-store`. Responses that carry tokens must not be cached. schema: type: string example: no-store Pragma: description: Always `no-cache`. schema: type: string example: no-cache responses: RateLimited: description: >- Too Many Requests - The rate limit for the OAuth application or the 1Password account was exceeded. Limits are shared across the token, introspection, and revocation endpoints. headers: Retry-After: description: How long to wait before retrying, in seconds. schema: type: integer example: 42 content: application/json: schema: $ref: '#/components/schemas/OAuthError' example: error: slow_down error_description: rate limit exceeded Internal: description: >- Internal Server Error - An unexpected error occurred. Retry the request later. content: application/json: schema: $ref: '#/components/schemas/OAuthError' example: error: server_error error_description: internal server error Unavailable: description: >- Service Unavailable - The service is temporarily unable to process the request. Retry the request later. content: application/json: schema: $ref: '#/components/schemas/OAuthError' example: error: server_error error_description: rate limiter unavailable securitySchemes: BasicAuth: type: http scheme: basic description: >- HTTP Basic authentication with the OAuth application's client credentials: the client ID as the username and the client secret as the password, joined with a colon and base64-encoded (`Authorization: Basic `). Tools such as curl encode the credentials for you when you pass them with `--user ":"`. Alternatively, send the credentials as the `client_id` and `client_secret` form fields in the request body. Don't use both methods in the same request. ```` ## Related topics - [1Password Users API](/users-api.md) - [1Password Users API reference](/users-api/reference.md) - [Authorize your integrations using OAuth 2.0](/users-api/authorization.md)