Skip to main content
POST
Mint an Ephemeral Key

Credential

Parent API key (cqt_… / ckey_…)

Processing

Realtime
Mints a short-lived Ephemeral Key - a signed RS256 JWT, prefixed gr_ek_, that you can safely hand to an untrusted client (browser, mobile app, WebSocket). The token carries no secret and expires on its own, so a stolen token is only useful until its exp. See the Ephemeral Keys guide for the full security model and recipes. Authenticate with your parent API key, not with an Ephemeral Key. An Ephemeral Key cannot mint another Ephemeral Key, and a gr_sk_… service key cannot mint either.
Platform endpoints on api.covalenthq.com require a trailing slash - call /platform/ephemeral_keys/, not /platform/ephemeral_keys.

Endpoint

Request

The request body is optional JSON. In this release the only accepted field is ttl_seconds; any other fields are ignored, and an Ephemeral Key always inherits the parent’s full access.
integer
default:"1800"
Requested lifetime in seconds. Defaults to 1800 (30 min). Clamped to [1, 3600] - the server maximum is 3600 (60 min), so larger requests are silently reduced to the cap. A non-integer value returns 400.

Example

Response

200 OK

Field descriptions

string
The signed RS256 JWT, prefixed gr_ek_. This is what you hand to the client. It carries no secret - it is trusted only because of its signature.
string
ISO-8601 UTC timestamp at which the token’s exp claim falls due. Refresh before this time.

Token claims

An Ephemeral Key is a standard RS256 JWT. Any verifier can decode it (no private key needed) and validate its signature against the Ephemeral JWKS endpoint. The signing key id (kid) travels in the JWT header, not the claims. There is no scopes claim in this release.

Use the Ephemeral Key

Hand the returned gr_ek_… token to your client and use it exactly where you would use an API key - as a Bearer token, Basic Auth username, or key query parameter - against the data APIs. It authenticates on behalf of the parent API key.
See the Ephemeral Keys quick start for the full mint-then-use flow.

Common uses

  • Browser / mobile embedding - mint on your backend, hand the gr_ek_… token to the client so it can call the data APIs directly without exposing your cqt_… key.
  • WebSocket auth - web-locked keys don’t cover WebSockets; an Ephemeral Key does. See Recipe B.
  • Per-session isolation - one token per client session, refreshed on a timer, so any single stolen token is short-lived.

Common errors

Errors are returned in the standard GoldRush envelope ({ "error": true, "error_message": …, "error_code": … }).
This endpoint is rate-limited per parent API key (default 60 mints/minute). Mint one Ephemeral Key per client session and refresh on a timer - do not mint a fresh token on every request.