Chalk home page
Docs
API
CLI
  1. Queries
  2. Authentication

Chalk implements OAuth for authentication to the online query interface. There are two kinds of credentials that can be used to access Chalk resources:

  • Personal Credentials: Full access to all resources on your account. This allows a client to act as you.
  • Service Credentials: Access scoped to a specific project and environment. Used for computers to talk to Chalk. Generated via the web dashboard.

Both personal and service credentials can be used to query Chalk, and potentially to modify your Chalk deployment’s settings. This means that these credentials are sensitive and must be kept secret.

When you use the CLI to create credentials, you will be asked to authenticate yourself on Chalk’s web dashboard. Then, you will receive a client_id and client_secret. Once generated, client_id cannot be changed. However, client_secret can be rotated if your security practices require this or if you suspect that client_secret has been compromised.

Once you have generated your client_id and client_secret, you can proceed to make authenticated requests to Chalk.

​
Authenticating an API client

Chalk has published API client libraries for several languages. These libraries handle exchanging a client_id and client_secret for an access_token which can be used to access Chalk.

from chalk.client import ChalkClient

client = ChalkClient(client_id="...", client_secret="...")

client.query(
    input={
        User.id: "1",
    },
    output=[
        User.identity.is_voip_phone,
        User.fraud_score
    ]
)

​
Authenticating CURL

We recommend using the chalk cli tool to authenticate a curl request. You can use chalk token to acquire an access_token that is suitable for use as a Bearer token:

curl -H "Authorization: Bearer $(chalk token)" \
  https://api.chalk.ai/v1/who-am-i

​
Fetching an Access Token

If you’re implementing a custom API client for a language that Chalk hasn’t published a library for, you may need to fetch an access_token using the OAuth Client Credentials grant flow. You can use the token endpoint in Chalk’s API to execute this flow:

​
Request

POST
https://api.chalk.ai/v1/oauth/token
Attributes
client_idstring
Your client_id
client_secretstring
Your client_secret
grant_typeclient_credentials
The grant_type field must always be "client_credentials".

​
Response

Attributes
access_tokenstring
The access_token that you should use in the Authorization header for authenticated requests.
expires_inint
Number of seconds until the access_token expires.
token_typestring
This field will always be "Bearer"

​
Authenticating a Request Using an Access Token

Use the token obtained from the Client Credentials grant flow in the Authorization: Bearer <ACCESS_TOKEN> header that your client sends along all authenticated requests. For example:

curl -H "Authorization: Bearer <ACCESS_TOKEN>" https://api.chalk.ai/v1/who-am-i

will return a 200 response and a JSON object containing a short description of the requesting user. This is convenient for verifying that you are using a valid access_token.

​
Role-based access control (RBAC)

Use service credentials to limit your application’s access to specific data sources and features.

​
Data sources

For data sources, you can provide an allowlist of tags when creating the service credential. Your service credential will only be allowed to access data sources whose tags match your allowlist.

​
Features

For features, Chalk expects a blocklist of tags. Features that match these tags will be excluded from computation. We make a distinction between features solely used to compute other features and features which are returned as query output. You can maintain separate blocklists for each of these types of features.