Authentication - Hexel Studio

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.

Python
TypeScript
CLI
curl

from hexel import Hexel

client = Hexel(api_key="YOUR_API_KEY")

import { Hexel } from "hexel-sdk";

const client = new Hexel({ apiKey: "YOUR_API_KEY" });

export HEXEL_API_KEY="YOUR_API_KEY"
hexel auth login

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

OAuth client credentials

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

Python
TypeScript
CLI
curl

from hexel import Hexel

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

import { Hexel } from "hexel-sdk";

const client = new Hexel({
  clientId: "YOUR_CLIENT_ID",
  clientSecret: "YOUR_CLIENT_SECRET",
});

export HEXEL_CLIENT_ID="YOUR_CLIENT_ID"
export HEXEL_CLIENT_SECRET="YOUR_CLIENT_SECRET"
hexel auth login

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)

Token exchange flow

Provide credentials

Send an API key (X-API-Key header) or client credentials (grant_type=client_credentials) to POST https://sts.hexelstudio.com/token.

Receive tokens

STS returns a Bearer token (access_token) and a refresh token.

Authenticate requests

Send Authorization: Bearer <token> on every API request.

Token response

string

Short-lived Bearer token. Valid for 15 minutes.

string

Used to obtain a new access token without re-authenticating.

integer

Seconds until the access token expires (900).

string

Always Bearer.

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:

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

API Keys

Create and manage API keys.

Service Accounts

Set up OAuth clients for production.

Organizations

How org, workspace, and environment scoping works.

Quickstart

Make your first authenticated request.

Next steps

Continue to First Deployment to take an agent from image to live endpoint.

​Authentication methods

​API key

​OAuth client credentials

​Token exchange flow

​Token response

​Environment variables

​Base URLs

​Common mistakes

​Best practices

​Related pages

API Keys

Service Accounts

Organizations

Quickstart

​Next steps

Authentication methods

API key

OAuth client credentials

Token exchange flow

Token response

Environment variables

Base URLs

Common mistakes

Best practices

Related pages

Next steps