ReferenceREST APIs

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

APIWhat it is forBase URLReference
Admin APIManage the organization: environments, packages and versions, connections, groups, permissions, API keys, workspaces, buildshttps://<org>.admin.credibledata.com/api/v0Admin API
Data APIQuery published models and connections: run and compile queries, list models, read dashboards, notebooks and data appshttps://<org>.data.credibledata.com/api/v0Data API
Retrieval APISearch a published model's sources, fields and values, the same search agents use through get_contexthttps://<org>.retrieval.credibledata.com/api/v1Retrieval API
Coding APIMalloy documentation search. Its other endpoints serve the VS Code extension and CLI and are not meant for integrationshttps://<org>.coding.credibledata.comCoding 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:

SchemeHeaderActs asUse it for
Bearer tokenAuthorization: Bearer <access-token>The signed-in userTesting, and scripts a person runs
API keyAuthorization: ApiKey <api-key>A groupServices, 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/environments

Tokens 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

  1. 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.

  2. 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.

  3. 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/environments

Tenant 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:

  1. 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.

  2. Filter the source on $GROUPS with 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()
    }
  3. 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.

Next Steps

On this page