Gemini Trust Authentication

generated: '2026-09-18'
method: searched
source: https://developer.gemini.com/authentication/api-key, https://developer.gemini.com/authentication/oauth, https://api.gemini.com/.well-known/oauth-authorization-server,
  plus openapi/gemini-trust-rest-openapi.yml and openapi/gemini-trust-prediction-markets-openapi.yml securitySchemes
summary:
  types:
  - apiKey
  - oauth2
  - openIdConnect
  api_key_in:
  - header
  note: The two OpenAPIs declare ONLY the three apiKey header schemes. OAuth 2.0 and the SSO OIDC surface are real
    and fully documented but are absent from both specs - a machine reading the contract alone would never discover
    the delegated-access model or its 33 scopes.
schemes:
- name: apiKey
  type: apiKey
  in: header
  parameter: X-GEMINI-APIKEY
  description: Gemini API key with appropriate permissions
  sources:
  - openapi/gemini-trust-prediction-markets-openapi.yml
  - openapi/gemini-trust-rest-openapi.yml
- name: payloadAuth
  type: apiKey
  in: header
  parameter: X-GEMINI-PAYLOAD
  description: Base64-encoded private REST payload. See Gemini private REST authentication.
  sources:
  - openapi/gemini-trust-prediction-markets-openapi.yml
  - openapi/gemini-trust-rest-openapi.yml
- name: signatureAuth
  type: apiKey
  in: header
  parameter: X-GEMINI-SIGNATURE
  description: Hex HMAC-SHA384 signature of the payload using the API secret.
  sources:
  - openapi/gemini-trust-prediction-markets-openapi.yml
  - openapi/gemini-trust-rest-openapi.yml
docs:
- https://developer.gemini.com/authentication/api-key
- https://developer.gemini.com/authentication/oauth
- https://developer.gemini.com/roles
models:
- name: API key (HMAC-SHA384)
  primary: true
  in_spec: true
  headers:
  - X-GEMINI-APIKEY
  - X-GEMINI-PAYLOAD
  - X-GEMINI-SIGNATURE
  - 'Content-Length: 0'
  - 'Content-Type: text/plain'
  - 'Cache-Control: no-cache'
  transport_note: 'Unusual and easy to get wrong: private REST requests send an EMPTY HTTP body. The JSON payload
    is base64-encoded into X-GEMINI-PAYLOAD, and X-GEMINI-SIGNATURE is hex(HMAC_SHA384(base64(payload), key=api_secret)).
    Gemini warns explicitly that generic OpenAPI-generated clients do not implement this signing transport.'
  key_prefixes:
    account-: account-scoped key
    master-: master key spanning sub-accounts; requires an account parameter
  replay_protection:
    field: nonce
    modes:
    - name: time-based (recommended)
      rule: Unix epoch seconds, validated within +/- 30 seconds of server time
    - name: incremental
      rule: strictly increasing per API session key
    error: InvalidNonce
  sessions: Each API key is an independent session with its own nonce sequence; Cancel-on-Disconnect ties open orders
    to a session heartbeat.
  provision: https://exchange.gemini.com/settings/api
- name: OAuth 2.0 authorization code
  primary: false
  in_spec: false
  grants:
  - authorization_code
  - refresh_token
  pkce: S256; REQUIRED for public clients (SPA, mobile, desktop). Client type is permanent at app creation.
  client_types:
  - confidential (client_id + client_secret)
  - public (client_id only, PKCE)
  token_lifetime:
    access_token: 24 hours
    refresh_token: non-expiring
  review: Gemini reviews registered applications before production activation; sandbox registration is immediate.
  scopes: 33 published - see scopes/gemini-trust-scopes.yml
  revocation:
  - https://exchange.gemini.com/auth/token/revoke
  - REST operation revokeOAuthToken (POST /v1/oauth/revokeByToken)
  metadata: https://api.gemini.com/.well-known/oauth-authorization-server (RFC 8414)
- name: OpenID Connect (SSO)
  primary: false
  in_spec: false
  scope: Exchange SSO only, not the trading API
  issuer: https://exchange.gemini.com
  signing: RS256
  client_auth: private_key_jwt
  scopes:
  - openid
  - email
  metadata: https://api.gemini.com/.well-known/openid-configuration
- name: WebSocket authentication
  primary: false
  in_spec: asyncapi
  methods:
  - X-GEMINI-APIKEY + X-GEMINI-NONCE + X-GEMINI-PAYLOAD + X-GEMINI-SIGNATURE on the connection upgrade
  - 'Authorization: Bearer <OAuth token>'
  docs: https://developer.gemini.com/websocket/authentication
authorization:
  model: role-based access control per API key
  roles:
  - Administrator (Master keys only - create and view accounts in the Master Group)
  - Trader (assigned by default)
  - Fund Manager
  - Auditor
  failure: HTTP 403 with reason MissingRole
  docs: https://developer.gemini.com/roles
  ip_allowlist: Group-level IP allowlisting is enforced; a request from an off-list address returns reason RemoteAddressForbidden.