Authentication and API conventions

The canonical API base is https://app.graypass.org/api/v1. The API origin https://api.graypass.org also supports the canonical JSON routes; documentation and application UI live on the app origin. Use one reviewed endpoint consistently in your configuration. The API version reported by metadata is 2026-10-01.

Credential boundaries

Authenticated server requests carry Authorization: Bearer with a secret credential stored on the backend. Browser requests use the short-lived client token minted by that backend for the signed-in subject and a registered origin. Do not put credentials in query strings or expose a server credential in a browser bundle.

The operation reference identifies which endpoints require server or admin authority. Credentials access resources within their own environment. Configure Console roles for people and API scopes for service credentials separately. See Console.

Check identity and origin

Call the credential-identity endpoint before setup to confirm tenant, environment, environment kind, scope, key mode, and proof issuer. The proof verifier still requires a trusted expected issuer; configure it for the service rather than copying an issuer from an unverified proof.

Browser origins include scheme, hostname, and port when used. Register the exact intended origin before minting a token. A token is short-lived and subject-bound; refresh it through your own authenticated backend. Apply application authentication and CSRF protection alongside origin registration.

Request conventions

JSON request models reject undeclared fields where specified by the contract. Use the exact snake_case wire fields shown in the generated reference; the Node SDK translates its documented camelCase inputs. Omit optional values rather than sending an unintended type. Canonical action material accepts safe integers, not floating-point values.

List responses and subject export are bounded. Use each endpoint's documented pagination parameters and collection bounds. Date strings explicitly requiring timezone information must include it; authorization requested_at uses Unix seconds.

Most resource timestamps are ISO 8601 strings. The token-issuance response instead uses Unix seconds for expires_at; evidence frames use the SDK's documented clock convention. Read each field's unit rather than applying one date parser to every numeric timestamp.

Retry and idempotency

Authorization binds an idempotency key and nonce to one request. Reuse them only when retrying identical material. Reconcile a conflict or stale result before obtaining fresh authorization. Follow each operation's documented retry and idempotency contract.

The authorization request timestamp must be no older than 300 seconds and no more than 60 seconds in the future. It is excluded from the action hash and idempotency comparison, so a retry may refresh that timestamp while preserving the original nonce, key and business material. A lifecycle or policy change can still make the stored authorization stale.

Use bounded backoff for rate limiting and transient transport errors. Keep the operation pending or refuse it while the response is uncertain. A timeout after online proof consumption needs application-state reconciliation before any further execution.

Public discovery

Metadata and the proof JWKS are public discovery surfaces. Metadata identifies the contract and capability states. JWKS publishes public verification keys while keeping customer records and private signing material protected. Fetch it from the configured trusted origin. The remaining operations below document credential inspection and browser token issuance in detail.

GET /.well-known/graypass-proof-keys.json

{
  "keys": []
}

POST /api/v1/client-tokens

{
  "subject": "sub_example",
  "origin": "https://merchant.example",
  "ttl_seconds": 900
}

{
  "expires_at": 1790856900,
  "ttl_seconds": 900,
  "origin": "https://merchant.example"
}

GET /api/v1/credential

{
  "credential": "key_example",
  "tenant": "tenant_example",
  "environment": "env_example",
  "environment_kind": "sandbox",
  "scope": "server",
  "mode": "test",
  "proof_issuer": "https://app.graypass.org"
}

GET /api/v1/meta

{
  "api_version": "2026-10-01"
}