Authenticate every customer-data request
Hyran Data V1 REST uses scoped API credentials in the HTTP Bearer authentication scheme. A credential is bound to one WorkOS organization, one regional cell, an allowlist of scopes, an optional expiry, and a revocation state. The API stores only a public identifier, prefix, scope metadata, and a cryptographic hash of the secret.
Send a credential
Authorization: Bearer hyran_data_live_us1_public-id.secret
The value above is illustrative and is not a working credential. Send a real credential only to the exact HTTPS API origin issued by Hyran.
Scope model
| Scope | Allows | Does not allow |
|---|---|---|
graph:read | Entity discovery and bounded relationship traversal | BOM history or exports |
bom:read | Completed snapshots, yields, and yield changes | Entity graph or exports |
exports:create | Create, inspect, and download owned export jobs | Reading another tenant's jobs |
mcp:read | Call the documented MCP tool allowlist | Arbitrary SQL, tools, or tenant selection |
Rotate a credential
Issue a replacement credential
Ask an authorized Hyran operator for the same minimum scopes and a suitable expiry.
Update the consumer secret
Replace the value in the integration secrets platform. Do not change tenant inputs because none are accepted.
Prove the replacement works
Make a bounded read and record its request ID before removing the old credential.
Revoke the old credential
Confirm that the old credential returns
401 invalid_token. Revocation is immediate for new requests.
Authentication failures
A missing, malformed, expired, revoked, or unknown credential returns 401 with
WWW-Authenticate: Bearer. A valid credential without the required scope returns 403. Neither
response reveals whether a requested customer object exists.
See Errors and rate limits for the full problem response and retry rules.
OAuth for interactive MCP clients
Interactive clients such as Codex sign in through auth.hyran.co and may use OAuth access on /mcp
and the documented governed read routes. OAuth tokens are rejected on exports and other write routes.
Hyran Data validates the exact issuer, MCP address, expiry, signed-in user, WorkOS organization, and
approved client. It then verifies active organization access, current membership, role permissions,
approved tools, regional placement, quotas, and RLS.
An organization claim identifies context but does not grant access by itself. Connection details are
published at /.well-known/oauth-protected-resource/mcp. If membership, organization access, or client
approval is removed, new requests fail closed. The first sign-in registers the client but does not grant
data access. A Hyran administrator must approve that exact client ID for the organization, read-only
tools, allowed datasets, quotas, and a versioned policy before tools become available.