Authentication

The CipherOwl API uses OAuth 2.0 authentication. After registration, you'll receive a client_id and client_secret to obtain access tokens for API requests.

📘

Building a client?

This page covers the token request itself. For a complete client that caches the token, refreshes on 401, and backs off on rate limits, see Build a CipherOwl Client.

How to Get client_id and client_secret

To get your client_id and client_secret, sign up at the CipherOwl application. Your credentials will be issued as part of the onboarding flow.

If you need help or run into issues during onboarding, reach out to CipherOwl Support.

How to Obtain an OAuth Token

Obtain an access token by making a POST request to the OAuth endpoint with your client_id and client_secret.

Example Request to Obtain OAuth Token

curl --request POST \
     --url https://svc.cipherowl.ai/oauth/token \
     --header 'Content-Type: application/json' \
     --data '{
         "client_id": "{YOUR_CLIENT_ID}",
         "client_secret": "{YOUR_CLIENT_SECRET}",
         "audience": "svc.cipherowl.ai",
         "grant_type": "client_credentials"
     }'

Need this in Python, Go, TypeScript, or Java? See Build a CipherOwl Client for full clients that also handle token caching, refresh, and retries.

The response includes an access_token for authenticating API requests:

{
  "access_token": "{your_access_token}",
  "scope": "{your_scopes}",
  "expires_in": 86400,
  "token_type": "Bearer"
}

How to Use access_token

Include the access_token in the Authorization header as a Bearer token for all API requests.

curl --request GET \
     --url 'https://svc.cipherowl.ai/api/screen/v1/chains/bitcoin/addresses/339khCuymVi4FKbW9hCHkH3CQwdopXiTvA?config=co-high_risk_hops_0' \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'

Token Expiration

Access tokens expire after a specified period. When you receive a 401 Unauthorized response, request a new token using the same OAuth endpoint and credentials.

Security

Keep your client_id, client_secret, and access_token confidential. Do not expose credentials in public repositories or insecure locations.

If credentials are compromised, immediately contact CipherOwl Support to revoke and replace them.

📘

Note

All OAuth tokens are rate-limited. Monitor your usage to avoid exceeding limits.