API Authentication

Creating an API key

In order to use any developer tool, you must first create an API key.

To create an API key, please visit the API settings page on your Monte Carlo dashboard and click Add, then select the key type and expiration period for your new key.

In addition, you can create an API key from Monte Carlo's onboarding wizard.

Monte Carlo supports both personal and account-level keys. The ability to create account-level keys is governed by role permissions (granted to Account Owners by default; custom roles can grant it to others).

API keys are generated from 42 cryptographically secure random bytes and base64 encoded, generating a 56 characters long string.

To authenticate API calls, you will need to include the following headers in your request:

For example, try running the following command in your terminal to test the API using your API key:

Test Query

curl --location --request POST 'https://api.getmontecarlo.com/graphql' --header 'x-mcd-id: <ID>'

Authenticating with OAuth (client credentials)

As an alternative to API keys, Monte Carlo supports OAuth 2.0 client credentials. Instead of sending a static key on every request, your application exchanges a client ID and secret for a short-lived JWT access token and sends it as a Bearer token. This is well suited to machine-to-machine (M2M) integrations.

Creating an OAuth client

Visit the API settings page on your Monte Carlo dashboard, click Add, and choose an OAuth client:

• Personal — an OAuth client tied to your user. Most users can create one by default (governed by the create personal OAuth clients permission).
• Service — an account-level OAuth client not tied to a person, with its own authorization groups. Creating one is governed by the create service OAuth clients permission (granted to Account Owners by default; custom roles can grant it to others).

When the client is created, Monte Carlo shows the Client ID and Client secret, along with the exact values you need to request a token:

• Scope — the API access scope plus your deployment's instance-routing scope, e.g. https://api.getmontecarlo.com/access https://instance.getmontecarlo.com/<instance_id> (where <instance_id> is your deployment, such as us1 or eu1).
• Token URL — where to request the access token, e.g. https://api.getmontecarlo.com/oauth2/token.
• API URL — where to send authenticated GraphQL requests, e.g. https://api.getmontecarlo.com/graphql.

Requesting an access token

Exchange the client credentials for an access token with a standard client-credentials grant, requesting the scope shown in the dialog:

curl --location --request POST '<TOKEN_URL>' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'client_id=<CLIENT_ID>' \
  --data-urlencode 'client_secret=<CLIENT_SECRET>' \
  --data-urlencode 'scope=https://api.getmontecarlo.com/access https://instance.getmontecarlo.com/<instance_id>'

The response contains an access_token (a JWT) and its expires_in lifetime in seconds.

Calling the API

Send the access token as a Bearer token in the Authorization header against the API URL:

curl --location --request POST '<API_URL>' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{"query": "query { getUser { email } }"}'

When the token expires, request a new one. Most integrations — including the CLI and Python SDK — handle this token exchange for you once configured with the client ID, secret, and instance ID.