> ## Documentation Index
> Fetch the complete documentation index at: https://docs.occtoo.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Request an Application access token
> Exchange Application or Data Provider credentials for a short-lived Occtoo access token.
Use **Try it** to exchange an Application's or Data Provider's client credentials for a short-lived access token. The audience identifies the API the token targets, while the optional scope limits what the token can do.
Treat the client secret and returned access token as secrets. Use the playground only for direct testing. Do not copy either value into browser application code, source control, logs, or client-side configuration.
## Choose an audience and scope
| Use case | Audience | Scope |
| -------------------------------------------------- | -------------- | ------------------- |
| Call a protected destination API version | API version ID | Leave empty |
| Ingest data | Tenant ID | `write:sources` |
| Legacy import or media ingest with a Data Provider | Tenant ID | `import-datasource` |
| Use every Events API transport | Tenant ID | `read:events` |
| Pull events and inspect metadata | Tenant ID | `read:events:pull` |
| Stream events with SSE | Tenant ID | `read:events:sse` |
Omit `scope` with the tenant audience to request every tenant API scope enabled for the Application.
## Data Provider access token
For legacy import and media ingest, send a `client_credentials` request to `https://auth.occtoo.com/oauth2/token`. Use the OAuth client ID and client secret for your [Data Provider](/guides/studio/sources/add-a-data-provider), your tenant ID as `audience`, and `import-datasource` as `scope`. Send the returned `access_token` as a bearer token to the Ingest API and reuse it until it expires.
See [Applications](/concepts/applications) for the complete access model, resource restrictions, language examples, and troubleshooting guidance.
## OpenAPI
````yaml api-reference/openapi/applications.json POST /oauth2/token
openapi: 3.1.1
info:
title: Occtoo application authentication
description: Obtain short-lived access tokens for an Occtoo Application or Data Provider.
version: 1.0.0
servers:
- url: https://auth.occtoo.com
description: Occtoo production authentication service
security: []
paths:
/oauth2/token:
post:
summary: Request an Application access token
description: >-
Exchanges an Application's or Data Provider's client credentials for a
short-lived access token. Use the tenant ID as the audience for ingest,
media, and events. Use an API version ID as the audience for a protected
destination API.
operationId: requestApplicationAccessToken
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
grant_type:
type: string
enum:
- client_credentials
default: client_credentials
description: >-
OAuth grant used by machine-to-machine Applications and Data
Providers.
client_id:
type: string
description: OAuth client ID of the Application or Data Provider.
example:
client_secret:
type: string
format: password
writeOnly: true
description: >-
Client secret of the Application or Data Provider. Treat
this value as a secret.
example:
audience:
type: string
description: >-
Tenant ID for ingest and events, or API version ID for a
protected destination API.
example:
scope:
type: string
description: >-
Optional space-delimited scopes. Use import-datasource for a
Data Provider. Omit for destination access or to request
every tenant scope granted to an Application.
examples:
- write:sources
- import-datasource
- read:events
- read:events:pull
- read:events:sse
required:
- grant_type
- client_id
- client_secret
- audience
examples:
ingest:
summary: Access the Ingest API
value:
grant_type: client_credentials
client_id:
client_secret:
audience:
scope: write:sources
dataProvider:
summary: Access legacy import and media ingest
value:
grant_type: client_credentials
client_id:
client_secret:
audience:
scope: import-datasource
events:
summary: Access every Events API transport
value:
grant_type: client_credentials
client_id:
client_secret:
audience:
scope: read:events
destination:
summary: Access a protected destination API version
value:
grant_type: client_credentials
client_id:
client_secret:
audience:
responses:
'200':
description: Access token issued.
content:
application/json:
schema:
$ref: '#/components/schemas/TokenResponse'
example:
access_token:
token_type: Bearer
expires_in: 3600
scope: write:sources
'400':
description: The request is malformed or contains an invalid scope.
content:
application/json:
schema:
$ref: '#/components/schemas/OAuthError'
'401':
description: The client credentials are invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/OAuthError'
'403':
description: >-
The Application is not authorized for the requested audience or
scope.
content:
application/json:
schema:
$ref: '#/components/schemas/OAuthError'
security: []
components:
schemas:
TokenResponse:
type: object
properties:
access_token:
type: string
description: Bearer token to send to the target API.
token_type:
type: string
const: Bearer
expires_in:
type: integer
description: Token lifetime in seconds.
scope:
type: string
description: Space-delimited scopes included in the token.
required:
- access_token
- token_type
- expires_in
OAuthError:
type: object
properties:
error:
type: string
error_description:
type: string
required:
- error
````