> ## Documentation Index
> Fetch the complete documentation index at: https://docs.credibledata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Access

> Build on the REST APIs

Build programmatically on your semantic models with the REST APIs — the same governed models that power workspaces, agents, and data apps, with the same access rules enforced on every request. Sign in as yourself with a **Bearer token**, or — for anything running server-to-server, like custom applications, scripts, and integrations — use an **API key** scoped to a group. The key acts with the group's permissions, so you can adjust what it can access at any time without regenerating it.

<Note>
  Looking to embed interactive analytics in a product? Build a **data app** — a full HTML/JavaScript application shipped with your package and served by Credible. See [Build Data Apps](/how-to/analyzing/data-apps) for how they're built and used.
</Note>

## The REST APIs

Credible provides three distinct APIs that align with the [platform architecture](/concepts/architecture): the **Admin API** for management operations, the **Data API** for high-throughput queries, and the **Retrieval API** for semantic search over your models. This separation ensures administrative operations never impact query workloads, and each plane can scale independently.

<CardGroup cols={3}>
  <Card title="Admin API" icon="gear" color="#94793A" href="/admin-api-reference">
    Manage organizations, environments, packages, connections, and permissions
  </Card>

  <Card title="Data API" icon="database" color="#5C7A93" href="/data-api-reference">
    Query semantic models programmatically and retrieve results
  </Card>

  <Card title="Retrieval API" icon="brain-circuit" color="#B8902E" href="/retrieval-api-reference">
    Search semantic model context — the same retrieval that powers the [Analytics Engine](/how-to/analyzing/overview)
  </Card>
</CardGroup>

## Authentication

Every request to the REST APIs carries an `Authorization` header, and Credible accepts two schemes:

| Scheme           | Header                                 | Acts as            | Best for                                          |
| ---------------- | -------------------------------------- | ------------------ | ------------------------------------------------- |
| **Bearer token** | `Authorization: Bearer <access-token>` | The signed-in user | Interactive use, testing, scripts run by a person |
| **API key**      | `Authorization: ApiKey <api-key>`      | A group            | Server-to-server: applications, services, CI/CD   |

### Bearer Tokens (User Auth)

Credible's APIs are a standard OAuth resource server: they accept access tokens issued by Credible's identity provider (Auth0) through your organization's SSO. When you sign in — in the browser or via the CLI's device flow — you get a short-lived access token, and every request made with it acts with **your** permissions, enforced by the same access rules as every other surface.

The easiest way to get a token is the CLI:

```bash theme={"languages":{"custom":["/languages/motly.tmGrammar.json","/languages/malloy.tmGrammar.json"]}}
cred login <your-org>
```

After login, the CLI stores your tokens in `~/.cred` and uses them for every command. For quick API testing, you can pass the same access token directly:

```bash theme={"languages":{"custom":["/languages/motly.tmGrammar.json","/languages/malloy.tmGrammar.json"]}}
curl -H "Authorization: Bearer <access-token>" \
  https://<your-org>.data.credibledata.com/api/v0/projects
```

Bearer tokens expire and are refreshed through the OAuth flow, so they're the right fit for interactive use — for anything long-running or unattended, use an API key instead.

## Create an API Key

### 1. Create a Group

Navigate to `yourorg.app.credibledata.com`:

1. Click **Users & Groups** in the bottom left of the sidebar
2. Switch to the **Groups** tab
3. Click **+ Create Group** and name your group (e.g., `ai_agents_group`)

### 2. Grant Environment Access

Navigate to the environment you want this group to access:

1. Click **Permissions** on the environment page
2. Add your group and select the appropriate role
3. Verify the group appears in the permissions list

### 3. Generate the Key (CLI)

Install the [Credible CLI](/platform-admin/cli), authenticate, and generate an API key for your group:

```bash theme={"languages":{"custom":["/languages/motly.tmGrammar.json","/languages/malloy.tmGrammar.json"]}}
# Install the CLI globally
npm i -g @credibledata/cred-cli

# Login to your organization
cred login <your-org>

# Create a group access token
cred add group-access-token <group-name> <token-name>
```

The final command outputs the API key. Store it securely in your application's credential storage or environment variables — all requests made with it act with the permissions of the group.

## Using the Key

Pass the key in the Authorization header on every request:

```
Authorization: ApiKey your-api-key
```

This works across Credible's programmatic surfaces: the REST APIs above, and the [MCP server](/how-to/analyzing/ai-assistants-mcp#connecting-custom-agents) for custom agents.

Have custom authentication requirements? [Contact us](mailto:support@credibledata.com) to discuss your use case.