Service Accounts - Hexel Studio

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.

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

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

Python SDK
curl (client_credentials)
Environment variables

from hexel import Hexel

client = Hexel(
    client_id="YOUR_CLIENT_ID",
    client_secret="YOUR_CLIENT_SECRET",
)

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

export HEXEL_CLIENT_ID="YOUR_CLIENT_ID"
export HEXEL_CLIENT_SECRET="YOUR_CLIENT_SECRET"

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.

API Keys

Simpler credentials for development.

Authentication

The client-credentials flow.

Environments

Scope service accounts per environment.

Members & Roles

Control who can create service accounts.

​When to use service accounts vs API keys

​How it works

​Getting started

​Common mistakes

​Best practices

​Related pages

API Keys

Authentication

Environments

Members & Roles

When to use service accounts vs API keys

How it works

Getting started

Common mistakes

Best practices

Related pages