--- title: Request and response headers description: The headers you send to the Hexel Studio API and the token service, and the headers they return. url: https://hexelstudio.com/docs/identity/headers --- 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`](#authorization) | One of `Authorization` or `X-API-Key` | `Bearer` access token for the API. `Basic` client credentials at the token endpoint. | | [`X-API-Key`](#x-api-key) | One of `Authorization` or `X-API-Key` | A service user's API key. | | [`X-Organization-Id`](#x-organization-id) | No | Must match the organization of your token or key. | | [`X-Workspace-Id`](#x-workspace-id-and-x-environment-id) | Sometimes | The workspace the request acts in. | | [`X-Environment-Id`](#x-workspace-id-and-x-environment-id) | Sometimes | The environment the request acts in. Needs `X-Workspace-Id`. | | [`Idempotency-Key`](#idempotency-key) | No | Makes organization creation safe to retry. | | [`Content-Type`](#content-type) | With a body | `application/json`. The token endpoint also accepts a form body. | | [`X-Request-Id`](#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](https://hexelstudio.com/docs/identity/roles). 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](https://hexelstudio.com/docs/identity/authenticate#use-oauth-client-credentials). ### X-API-Key ```http X-API-Key: studio_live_... ``` A service user's [API key](https://hexelstudio.com/docs/identity/service-users#api-keys). 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](https://hexelstudio.com/docs/identity/authenticate#exchange-an-api-key-for-an-access-token) for those. ### X-Organization-Id ```http X-Organization-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: X-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](https://hexelstudio.com/docs/identity/roles#using-a-role-session), 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](https://hexelstudio.com/docs/identity/organizations). ### 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](https://hexelstudio.com/docs/identity/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.