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

# Authentication

> Authenticate to Hexel Studio with API keys or OAuth client credentials.

Every request to Hexel Studio is authenticated with a short-lived Bearer token. You provide an API key or OAuth client credentials, and Hexel exchanges them for a token and refreshes it automatically.

## Authentication methods

Hexel supports two credential types: an API key for development and quick scripts, and OAuth client credentials for production services that need scoped, rotatable secrets.

| Method                       | Best for                              | Credential                             |
| ---------------------------- | ------------------------------------- | -------------------------------------- |
| **API Key**                  | Development, scripts, quick testing   | A single secret key                    |
| **OAuth Client Credentials** | Production services, server-to-server | A `client_id` and `client_secret` pair |

Create both in the Console under **IAM → Service Users**.

## API key

Provide the key and the client handles token exchange and refresh.

<Tabs>
  <Tab title="Python">
    ```python theme={"dark"}
    from hexel import Hexel

    client = Hexel(api_key="YOUR_API_KEY")
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={"dark"}
    import { Hexel } from "hexel-sdk";

    const client = new Hexel({ apiKey: "YOUR_API_KEY" });
    ```
  </Tab>

  <Tab title="CLI">
    ```bash theme={"dark"}
    export HEXEL_API_KEY="YOUR_API_KEY"
    hexel auth login
    ```
  </Tab>

  <Tab title="curl">
    ```bash theme={"dark"}
    # Exchange the API key for a Bearer token
    TOKEN=$(curl -s -X POST https://sts.hexelstudio.com/token \
      -H "X-API-Key: YOUR_API_KEY" | jq -r .access_token)

    # Use the token
    curl https://api.hexelstudio.com/compute/v1/instances \
      -H "Authorization: Bearer $TOKEN"
    ```
  </Tab>
</Tabs>

## OAuth client credentials

Recommended for production and any server-to-server integration.

<Tabs>
  <Tab title="Python">
    ```python theme={"dark"}
    from hexel import Hexel

    client = Hexel(
        client_id="YOUR_CLIENT_ID",
        client_secret="YOUR_CLIENT_SECRET",
    )
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={"dark"}
    import { Hexel } from "hexel-sdk";

    const client = new Hexel({
      clientId: "YOUR_CLIENT_ID",
      clientSecret: "YOUR_CLIENT_SECRET",
    });
    ```
  </Tab>

  <Tab title="CLI">
    ```bash theme={"dark"}
    export HEXEL_CLIENT_ID="YOUR_CLIENT_ID"
    export HEXEL_CLIENT_SECRET="YOUR_CLIENT_SECRET"
    hexel auth login
    ```
  </Tab>

  <Tab title="curl">
    ```bash theme={"dark"}
    TOKEN=$(curl -s -X POST https://sts.hexelstudio.com/token \
      -d "grant_type=client_credentials" \
      -d "client_id=YOUR_CLIENT_ID" \
      -d "client_secret=YOUR_CLIENT_SECRET" | jq -r .access_token)
    ```
  </Tab>
</Tabs>

## Token exchange flow

<Steps>
  <Step title="Provide credentials">
    Send an API key (`X-API-Key` header) or client credentials (`grant_type=client_credentials`) to `POST https://sts.hexelstudio.com/token`.
  </Step>

  <Step title="Receive tokens">
    STS returns a Bearer token (`access_token`) and a refresh token.
  </Step>

  <Step title="Authenticate requests">
    Send `Authorization: Bearer <token>` on every API request.
  </Step>
</Steps>

### Token response

<ResponseField name="access_token" type="string">Short-lived Bearer token. Valid for 15 minutes.</ResponseField>
<ResponseField name="refresh_token" type="string">Used to obtain a new access token without re-authenticating.</ResponseField>
<ResponseField name="expires_in" type="integer">Seconds until the access token expires (900).</ResponseField>
<ResponseField name="token_type" type="string">Always `Bearer`.</ResponseField>

The SDKs and CLI cache the token and refresh it automatically before expiry. If you call the REST API directly with curl, re-exchange your credentials when the token expires.

## Environment variables

The SDKs and CLI read these automatically:

```bash theme={"dark"}
# API key authentication
export HEXEL_API_KEY="YOUR_API_KEY"

# OAuth client credentials
export HEXEL_CLIENT_ID="YOUR_CLIENT_ID"
export HEXEL_CLIENT_SECRET="YOUR_CLIENT_SECRET"
```

## Base URLs

Service endpoints for direct API use. The SDKs and CLI route to these automatically.

| Service                                       | Base URL                                              |
| --------------------------------------------- | ----------------------------------------------------- |
| Compute, Registry, Orchestration, Tools, Data | `https://api.hexelstudio.com`                         |
| Token service (STS)                           | `https://sts.hexelstudio.com`                         |
| Deployed agents (agent traffic)               | `https://agent-<name>-<hash>.compute.hexelstudio.com` |
| Deployed sandboxes (sandbox traffic)          | `https://sandbox-<id>.compute.hexelstudio.com`        |

## Common mistakes

* **Hardcoding keys in source.** Use environment variables or a secret manager.
* **Sharing one key across environments.** Use a separate key per environment to limit blast radius.
* **Using API keys in production services.** Prefer OAuth client credentials for server-to-server traffic.
* **Embedding keys in client-side code.** Credentials must never reach a browser or mobile client.

## Best practices

* Rotate keys periodically and immediately if one is exposed.
* Scope credentials to the narrowest workspace and environment needed.
* Store secrets in a managed secret store, not in version control.
* Let the SDKs manage token refresh rather than handling tokens yourself.

## Related pages

<CardGroup cols={2}>
  <Card title="API Keys" icon="key" href="/docs/iam/api-keys">
    Create and manage API keys.
  </Card>

  <Card title="Service Accounts" icon="robot" href="/docs/iam/service-accounts">
    Set up OAuth clients for production.
  </Card>

  <Card title="Organizations" icon="building" href="/docs/concepts/organizations">
    How org, workspace, and environment scoping works.
  </Card>

  <Card title="Quickstart" icon="rocket" href="/docs/getting-started/quickstart">
    Make your first authenticated request.
  </Card>
</CardGroup>

## Next steps

Continue to [First Deployment](/docs/getting-started/first-deployment) to take an agent from image to live endpoint.