Request and response headers

The headers you send to the Hexel Studio API and the token service, and the headers they return.

On this page

Request headers
Authorization
X-API-Key
X-Organization-Id
X-Workspace-Id and X-Environment-Id
Idempotency-Key
Content-Type
X-Request-Id
Response headers
Headers Hexel Studio removes or sets

This page lists the HTTP headers that the Hexel Studio API at https://api.hexelstudio.com and the token service at https://sts.hexelstudio.com read and return. Header names are case-insensitive.

Request headers

Header	Required	Used for
`Authorization`	One of `Authorization` or `X-API-Key`	`Bearer` access token for the API. `Basic` client credentials at the token endpoint.
`X-API-Key`	One of `Authorization` or `X-API-Key`	A service user's API key.
`X-Organization-Id`	No	Must match the organization of your token or key.
`X-Workspace-Id`	Sometimes	The workspace the request acts in.
`X-Environment-Id`	Sometimes	The environment the request acts in. Needs `X-Workspace-Id`.
`Idempotency-Key`	No	Makes organization creation safe to retry.
`Content-Type`	With a body	`application/json`. The token endpoint also accepts a form body.
`X-Request-Id`	No	At the token endpoint only: your own ID for the request.

Authorization

On https://api.hexelstudio.com, send an access token:

HTTP

Authorization: Bearer eyJhbGciOiJSUzI1NiIs...

The token can be a member's token, a service user's token or a role session. The API accepts only access tokens issued by https://sts.hexelstudio.com for the audience https://api.hexelstudio.com. A missing, expired or invalid token gets 401.

At https://sts.hexelstudio.com/token, Authorization: Basic ... carries an OAuth client's ID and secret, as an alternative to sending them in the body. See Use OAuth client credentials.

X-API-Key

HTTP

X-API-Key: studio_live_...

A service user's API key. The API exchanges it for an access token at the edge. The token endpoint accepts it to issue a token you can reuse.

If a request has both a bearer token and an API key, the bearer token is used.
Hexel Studio removes X-API-Key before the request reaches the service that handles it.
Some product APIs accept only a bearer token. Exchange the key for those.

X-Organization-Id

HTTP

X-Organization-Id: <org-id>

Every access token and API key belongs to one organization, and the request is made for that organization. You never need this header to choose an organization on the API. If you send it, it is checked:

Where	If it doesn't match
API request with a bearer token	The request is refused (`401` or `403`).
API request with `X-API-Key`	`403`: `X-Organization-Id does not match the API key's organization.`
`POST https://sts.hexelstudio.com/refresh`	`400`: a refresh can't change organization.

When the console signs a person in, it sends X-Organization-Id to the token service to choose which organization the new token is for. The person must be an active member of it.

Use X-Organization-Id, not the older X-Org-Id, which the identity and access APIs don't read.

X-Workspace-Id and X-Environment-Id

HTTP

X-Workspace-Id: <workspace-id>
X-Environment-Id: <environment-id>

These headers say which workspace, and which environment in it, a request acts in. The permission check uses them:

Permissions you hold across the organization apply with or without them.
Permissions granted only for a workspace or environment, such as those of a workspace or environment role, apply only when the request names that workspace or environment.
A workspace that isn't in your organization, an environment that isn't in the named workspace, or X-Environment-Id without X-Workspace-Id makes the permission check fail.

On routes whose path names a workspace or environment, such as /v1/workspaces/{workspace_id}/..., the permission check uses the IDs in the path instead of these headers. See Organizations, workspaces and environments.

Idempotency-Key

HTTP

Idempotency-Key: 6c0e6c9e-5d1f-4c55-9b0a-3f1f0f8c2a7d

Supported on POST /v1/organizations. Sending the same request again with the same key returns the organization created the first time instead of a second one. Reusing a key with a different request body is refused. Keys are at most 200 characters; a UUID works well. Without a key, an identical repeated request from the same person is also recognized as a retry.

Other Hexel Studio APIs that support Idempotency-Key say so in their reference.

Content-Type

Send Content-Type: application/json with every request body. The token endpoint (/token) also accepts application/x-www-form-urlencoded, and it decides how to read the body from this header.

X-Request-Id

On https://api.hexelstudio.com, Hexel Studio assigns every request its own ID. An X-Request-Id you send is replaced. At https://sts.hexelstudio.com, an X-Request-Id you send is kept and returned; without one, an ID is generated.

Response headers

Header	When	Meaning
`X-Request-Id`	Every response	The request's ID. Include it when you contact support.
`Retry-After`	`429` from a rate limit; `202` from `POST /v1/organizations/{organization_id}/provisioning/retry`	Seconds to wait before retrying.
`X-RateLimit-Limit`	`429` from a rate limit	The limit you exceeded, per minute.
`X-RateLimit-Scope`	`429` from a rate limit	Which limit you exceeded. See below.
`Content-Type`	Responses with a body	`application/json`.

X-RateLimit-Scope is one of:

Value	Limit
`principal_reads`	Reads by one user, service user or role.
`principal_writes`	Writes by one user, service user or role.
`principal_sensitive_writes`	Writes to API keys, OAuth clients, policies, members and invitations by one caller.
`org_reads`	Reads by everyone in the organization.
`org_writes`	Writes by everyone in the organization.
`token_issues`	Tokens issued for one credential at the token endpoint.

Rate limits count per calendar minute, so Retry-After is the number of seconds until the next minute starts. See Limits for the values.

A 429 for too many invalid API keys from one IP address has no Retry-After. Wait a minute before trying again.

Headers Hexel Studio removes or sets

On https://api.hexelstudio.com, before a request reaches the service that handles it:

X-API-Key is removed. When the key is valid, Hexel Studio adds an Authorization: Bearer header with a token for the key's service user.
X-Request-Id is replaced with Hexel Studio's own ID.
Headers that start with X-Hexel-Client- are removed. Hexel Studio sets them itself.

Identity, organization and permissions come only from the verified token. No header you send can change who you are or which organization a token is for.