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

# Service Accounts

> OAuth client credentials for production server-to-server access.

A service account is a non-human identity authenticated with OAuth client credentials (`client_id` and `client_secret`). It is the recommended way for production services to authenticate to Hexel Studio.

## When to use service accounts vs API keys

|                          | API Key                                                                                                                          | Service Account (OAuth)                                                                                           |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| **Identity model**       | Tied to a service user created by a person. If the person who created it leaves and the key is orphaned, there's no clear owner. | Tied to a service identity with its own lifecycle, independent of any individual.                                 |
| **Credential lifecycle** | Long-lived secret, manually rotated.                                                                                             | `client_id` + `client_secret` exchanged for short-lived tokens; secret rotation doesn't invalidate active tokens. |
| **Best for**             | Local development, scripts, CI during early setup.                                                                               | Production server-to-server integrations, long-running services, automated pipelines.                             |

<Tip>
  Use API keys for development. Use service accounts for anything that runs unattended in production — the identity persists regardless of team changes.
</Tip>

## How it works

Create an access client under **IAM → Service Users**, which issues a `client_id` and `client_secret`. Your service exchanges them with the STS (`sts.hexelstudio.com`) for a Bearer token (valid 15 minutes, refresh token valid 30 days). The SDKs handle this exchange and refresh automatically.

## Getting started

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

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

  <Tab title="curl (client_credentials)">
    ```bash theme={"dark"}
    # Exchange client credentials for an access token
    curl -X POST https://sts.hexelstudio.com/oauth/token \
      -H "Content-Type: application/x-www-form-urlencoded" \
      -d "grant_type=client_credentials" \
      -d "client_id=YOUR_CLIENT_ID" \
      -d "client_secret=YOUR_CLIENT_SECRET"

    # Response:
    # {
    #   "access_token": "eyJ...",
    #   "token_type": "Bearer",
    #   "expires_in": 900
    # }

    # Use the token in subsequent requests
    curl https://api.hexelstudio.com/compute/v1/agents \
      -H "Authorization: Bearer ACCESS_TOKEN"
    ```
  </Tab>

  <Tab title="Environment variables">
    ```bash theme={"dark"}
    export HEXEL_CLIENT_ID="YOUR_CLIENT_ID"
    export HEXEL_CLIENT_SECRET="YOUR_CLIENT_SECRET"
    ```
  </Tab>
</Tabs>

## Common mistakes

* **Using a personal API key in production.** Prefer a service account so the credential is not tied to an individual.
* **Storing the secret in code.** Keep it in a managed secret store.

## Best practices

* Use one service account per service, scoped to its environment.
* Rotate client secrets periodically.
* Revoke unused access clients promptly.

## Related pages

<CardGroup cols={2}>
  <Card title="API Keys" icon="key" href="/docs/iam/api-keys">
    Simpler credentials for development.
  </Card>

  <Card title="Authentication" icon="lock" href="/docs/getting-started/authentication">
    The client-credentials flow.
  </Card>

  <Card title="Environments" icon="layer-group" href="/docs/iam/environments">
    Scope service accounts per environment.
  </Card>

  <Card title="Members & Roles" icon="users" href="/docs/iam/members-and-roles">
    Control who can create service accounts.
  </Card>
</CardGroup>