> For the complete documentation index, see [llms.txt](https://docs.usedecentral.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.usedecentral.org/api-reference/authentication.md).

# Authentication

All API requests require a bearer token in the `Authorization` header. Tokens are API keys linked to a specific Solana wallet and its credit balance.

***

## API keys

API keys are generated from the Settings tab in the Decentral web app at `usedecentral.org/app/settings`.

**Key format:** `dcntrl_live_` followed by a 32-character alphanumeric string.

Example: `dcntrl_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6`

**Key properties:**

* One key per wallet during beta. Multiple keys per wallet are coming in Phase 2.
* Keys are linked to the credit balance of the wallet that created them. Spending credits via the API reduces the same balance visible in the web app.
* Keys can be revoked and regenerated from the Settings tab at any time.
* Keys are shown once at creation. If you lose your key, you must generate a new one.

***

## Making authenticated requests

Include the API key as a bearer token in every request:

```bash
curl https://api.usedecentral.org/v1/models \
  -H "Authorization: Bearer dcntrl_live_your_key_here"
```

```python
import httpx

headers = {"Authorization": "Bearer dcntrl_live_your_key_here"}
response = httpx.get("https://api.usedecentral.org/v1/models", headers=headers)
```

```typescript
const response = await fetch("https://api.usedecentral.org/v1/models", {
    headers: { "Authorization": "Bearer dcntrl_live_your_key_here" }
})
```

***

## Security

**Keep your API key private.** Do not commit it to version control or expose it in client-side code. Use environment variables.

```bash
export DECENTRAL_API_KEY="dcntrl_live_your_key_here"
```

```python
import os
api_key = os.environ["DECENTRAL_API_KEY"]
```

**Key scope:** An API key can only spend credits from the wallet that created it. It cannot withdraw credits, transfer $DECENTRAL, or modify account settings.

**Key revocation:** If you believe a key has been compromised, revoke it immediately from Settings. Revocation is instant and takes effect for all subsequent requests.

***

## Wallet-native authentication (coming in Phase 2)

In Phase 2, the API will support wallet-native authentication as an alternative to static API keys. Instead of a pre-generated key, you sign each request with your Solana wallet keypair. This allows programmatic use without a pre-shared secret and is better suited to automated environments where generating a static key is inconvenient.

***

## Authentication errors

| Status | Code                   | Meaning                                                     |
| ------ | ---------------------- | ----------------------------------------------------------- |
| `401`  | `invalid_api_key`      | The key does not exist or has been revoked                  |
| `401`  | `missing_api_key`      | No `Authorization` header was included                      |
| `402`  | `insufficient_credits` | Your credit balance is too low for the requested model tier |
| `403`  | `key_suspended`        | The key has been suspended due to a policy violation        |

See \[Errors]\(

) for full error response format.

***

## Checking your balance via the API

```bash
curl https://api.usedecentral.org/v1/account \
  -H "Authorization: Bearer dcntrl_live_your_key_here"
```

```json
{
  "wallet": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
  "credits_remaining": 1420,
  "usdc_value": 14.20,
  "last_topup_at": "2026-06-15T09:43:00Z",
  "api_key_created_at": "2026-06-01T00:00:00Z"
}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.usedecentral.org/api-reference/authentication.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.