REST APIs
The four Credible REST APIs and their base URLs, how to authenticate with a user's Bearer token or a group API key, and how to scope an API key to one tenant's rows
Scripts, services, CI and custom agents call Credible through four REST APIs, authenticated as a signed-in user or with a group's API key. Every request is checked against the same access rules as the Credible App and MCP, so a caller sees only what its user or group may see.
The REST APIs
| API | What it is for | Base URL | Reference |
|---|---|---|---|
| Admin API | Manage the organization: environments, packages and versions, connections, groups, permissions, API keys, workspaces, builds | https://<org>.admin.credibledata.com/api/v0 | Admin API |
| Data API | Query published models and connections: run and compile queries, list models, read dashboards, notebooks and data apps | https://<org>.data.credibledata.com/api/v0 | Data API |
| Retrieval API | Search a published model's sources, fields and values, the same search agents use through get_context | https://<org>.retrieval.credibledata.com/api/v1 | Retrieval API |
| Coding API | Malloy documentation search. Its other endpoints serve the VS Code extension and CLI and are not meant for integrations | https://<org>.coding.credibledata.com | Coding API |
Replace <org> with your organization's name. On a dedicated cluster the hostnames differ; Credible gives them to you. To give an agent access, the MCP server is usually simpler than these APIs, and accepts the same credentials.
Authentication
Every request carries an Authorization header in one of two forms:
| Scheme | Header | Acts as | Use it for |
|---|---|---|---|
| Bearer token | Authorization: Bearer <access-token> | The signed-in user | Testing, and scripts a person runs |
| API key | Authorization: ApiKey <api-key> | A group | Services, CI and anything unattended |
An API key works only for the organization it was created in.
Bearer Tokens
A Bearer token is the short-lived access token you get when you sign in, and a request made with it has exactly your access. The simplest way to get one is the CLI, which prints a current token and renews it when needed:
cred login <org>
curl -H "Authorization: Bearer $(cred token)" \
https://<org>.data.credibledata.com/api/v0/environmentsTokens expire, so use an API key for anything long-running or unattended.
API Keys
An API key (a group access token) acts as a Credible group, with every role the group holds, including organization admin if the group has it. Keys have no scopes of their own: to limit what a key can do, limit what its group can do. Changing the group's roles changes what its existing keys can reach, with no new key needed. Keys are created by organization admins, are shown once, and expire on the date you choose, or effectively never if you don't set one.
Create an API Key
-
Create a group for the integration. An organization admin creates it on the Users and Groups page, or with
cred add group <group>. Use a group that exists only for this integration, so its key has no access it doesn't need. -
Grant the group the access the integration needs. For querying or publishing in one environment, grant an environment role, for example
cred add permission group:<group> modeler --environment <environment>. Creating environments needs the organization admin role, which is a broad grant; use it only for an integration that provisions environments. What each role allows is on Permissions. -
Create the key. On the group's page in the Credible App, or with the CLI:
cred add group-access-token <group> <key-name> [--expires-at 2027-12-31T00:00:00Z]Copy the key when it is shown and keep it in a secret store or environment variable. To revoke it, delete it on the group's page or run
cred rm group-access-token <group> <key-name>.
Send it on every request:
curl -H "Authorization: ApiKey $CREDIBLE_API_KEY" \
https://<org>.data.credibledata.com/api/v0/environmentsTenant Isolation for Embedded Products
When your product calls Credible for several of your own customers, put the tenant rule in the model rather than in your application code. An API key's caller is its group, and a model can filter rows on the built-in $GROUPS given, which for a key holds the key's group and every group that group belongs to:
-
Create one group per tenant, named with the tenant's ID as it appears in your data, and create an API key for each group. Group names are matched exactly, including case.
-
Filter the source on
$GROUPSwith a row filter:##! experimental.givens given: #(secure) GROUPS :: string[] #(access_filter) tenant_id in $GROUPS source: orders is orders_core extend { measure: order_count is count() } -
Call Credible with the tenant's key. Every query through the Data API, the Retrieval API or MCP is filtered to that tenant's rows before it runs.
A bug in your application can then pick the wrong key, but it can't widen what a key returns. Custom secure givens that an admin assigns values to (such as a TENANTS list) are resolved for signed-in users, never for API keys. A key that queries a model declaring one is refused with a 403, even for a source that doesn't read it. Use $GROUPS for keys, in a model that declares no custom secure given. The rules themselves are covered in Row and Column Access.
For an interface your users open in Credible, ship a data app: it queries as the signed-in user, under the same rules.
Have a requirement this doesn't cover? Contact support.