API Authentication: OAuth 2.0 Client Credentials

Slate authenticates API requests using the OAuth 2.0 client_credentials grant. Exchange your client ID and secret at the token endpoint for a short-lived Bearer token, then include that token in the Authorization header on every API call. Tokens are scoped to an owner organization and carry permissions configured at client provisioning time.

Token Endpoints

Use the endpoint that matches your target environment:

Environment	Token URL
UAT	`https://api.uat.slate.inc/auth/v1/oauth2/token`
Production	`https://api.slate.inc/auth/v1/oauth2/token`

Requesting a Token

Send a POST request to the token endpoint with your client credentials and the client_credentials grant type. Credentials are passed via HTTP Basic auth (client ID as the username, client secret as the password).

curl --request POST \
  --url "https://api.slate.inc/auth/v1/oauth2/token" \
  --user "<client-id>:<client-secret>" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data "grant_type=client_credentials" \
  --data "scope=https://api.slate.inc/files/write https://api.slate.inc/accounts/write"

A successful response returns a JSON object containing the access token and its lifetime:

{
  "access_token": "eyJraWQiOiJ...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Cache the token for its expires_in window (minus a small buffer) and request a new one before it expires. Do not request a new token on every API call.

Scopes

Request one or more of the following scopes in the scope parameter, separated by spaces:

Scope	Grants
`https://api.slate.inc/files/write`	Read and write file resources
`https://api.slate.inc/signatures/write`	Read and write signatures
`https://api.slate.inc/accounts/write`	Read and write accounts
`https://api.slate.inc/users/write`	Read and write users
`https://api.slate.inc/qc/write`	Read and write QC records

Scopes are not yet enforced at the API layer, but they will be. Request only the scopes your integration needs today so it keeps working once enforcement is enabled. Actual access is currently governed by the permissions attached to your client at provisioning time.

Sending Your Token

Include the access token in the Authorization header with the Bearer scheme:

Authorization: Bearer <access-token>

Here is a complete example using curl:

curl --request GET \
  --url "https://api.slate.inc/accounts/v1/accounts" \
  --header "Authorization: Bearer <access-token>"

Each API is served under its own service prefix on api.slate.inc — for example /accounts, /files, /qc, /signatures, and /users. The same Bearer token works across every service. All requests, including GET, POST, PATCH, and DELETE, require this header.

Treat your client secret and access tokens like passwords. Never commit them to source control, log them, or expose them in client-side code. Store them in a secrets manager or environment variable.

Owner Scoping

Your client is bound to a single owner, the organization Slate uses to isolate your data. Slate delivers your owner identifier alongside your client credentials. Every account, file, signature, and QC record you create or retrieve is scoped to that owner automatically, and you do not need to pass the owner identifier on standard requests.

List endpoints

List endpoints require you to specify the owner explicitly to keep them context-free. Pass your owner identifier as a query parameter, and it must be an owner your token is authorized to read:

curl --request GET \
  --url "https://api.slate.inc/accounts/v1/accounts?owner=<owner-id>" \
  --header "Authorization: Bearer <access-token>"

Requests to list endpoints without an owner parameter will be rejected.

Getting Client Credentials

Slate does not provide self-serve client registration. To obtain a client ID and secret:

Contact your Slate account manager and provide the name or identifier of the service you are building, along with the scopes and permissions it needs.
Slate provisions a client scoped to your owner with the requested permissions and delivers the client ID, client secret, and owner identifier through a secure channel.
Store the client ID and secret in your secrets manager and reference them at runtime via environment variables (for example, SLATE_CLIENT_ID and SLATE_CLIENT_SECRET).

If your client secret is compromised or needs to be rotated, contact your account manager immediately.

Error Responses

Token endpoint errors

The token endpoint returns standard OAuth 2.0 error responses when a token request fails:

{
  "error": "invalid_client"
}

Common causes:

Error	What to do
`invalid_client`	Verify your client ID and secret are correct and sent via HTTP Basic auth
`invalid_grant`	Confirm `grant_type=client_credentials` is set
`invalid_scope`	Check that every requested scope is spelled correctly and provisioned for your client

API errors

When authentication fails on an API request, Slate returns 401 Unauthorized with a JSON body:

{
  "message": "Invalid or missing authorization credentials."
}

Common causes:

Cause	What to do
Token is missing from the request	Add the `Authorization: Bearer <access-token>` header
Token is expired	Request a new token from the OAuth endpoint
Token is malformed or truncated	Verify the full token value was copied correctly
Token has been revoked	Contact your Slate account manager for a replacement
Client lacks permission for the endpoint	Confirm the correct client is being used for this resource

Account identifier (crid) uniqueness

When you upsert accounts, you supply a crid (your identifier for the account in your own system), and that value must be unique within your owner. Two different owners may use the same crid without conflict, but within a single owner, each crid maps to exactly one Slate account. Because crid is the natural key the upsert matches on, re-sending the same crid updates the existing record rather than creating a new one.

Get Started

Core Concepts

Guides

API Authentication: OAuth 2.0 Client Credentials

Token Endpoints

Requesting a Token

Scopes

Sending Your Token

Owner Scoping

List endpoints

Getting Client Credentials

Error Responses

Token endpoint errors

API errors

Account identifier (crid) uniqueness

​Token Endpoints

​Requesting a Token

​Scopes

​Sending Your Token

​Owner Scoping

​List endpoints

​Getting Client Credentials

​Error Responses

​Token endpoint errors

​API errors

​Account identifier (crid) uniqueness

Token Endpoints

Requesting a Token

Scopes

Sending Your Token

Owner Scoping

List endpoints

Getting Client Credentials

Error Responses

Token endpoint errors

API errors

Account identifier (crid) uniqueness