Skip to main content

​
Authentication

Blank API v2 authenticates with a single credential type: a scoped, environment-bound, server-side API key, sent as an HTTP bearer token.
Anonymous read operations need no credential at all. Everything else requires a key that carries the required scopes.

​
What a key is bound to

A v2 API key belongs to exactly one:
  • Blank account — the account that created it.
  • Environment — production, staging, or development.
  • Wallet — that account’s single verified wallet, pinned at creation.
It also carries an explicit scope set, an expiry, a revocation state, and an auditable identifier. Ownership, scope, resource state, environment, rate policy, and any required wallet signature are re-checked on every protected request.
An API key never replaces a wallet signature. It authorizes preparing and submitting a transaction; the pinned wallet still has to sign the exact prepared message. See Operations and transaction intents.
Because a key is wallet-pinned, owner-scoped reads return only your own data. blank.staking.positions(), blank.presales.participation(), blank.predictions.get(), and blank.predictions.eligibility() can never see another wallet.

​
Delegated prediction authorization

predictions:delegate is a narrow exception to account-pinned prediction submission. The API key still identifies and authenticates only the server-side integration. It can create a five-minute prediction intent, but it cannot create the end user’s prediction until that user’s verified wallet signs Blank’s exact stored UTF-8 message. The message binds the environment, integration key ID and name, intent ID, round ID, wallet, canonical predicted price, and expiry. Blank rejects a signature for a changed message, an intent created by another key, an expired or consumed intent, or a wallet that is not currently verified on an eligible Blank account. This does not grant general impersonation. The scope cannot read the user’s private resources or authorize trading, staking, fees, presales, or transactions. See Delegated submissions for the server/browser/server flow.

​
Key format and environments

Both segments are URL-safe base64. Blank stores only a SHA-256 hash of the credential, so a lost secret cannot be recovered — rotate instead. A key is only accepted by the environment it was issued for. Presenting a blank_test_ key to production returns 401 invalid_api_key, and so does the reverse.

​
Create a key

Keys are created in the Blank app, not through the API.
  1. Sign in at blank.build and open Settings.
  2. Set a username first. Key creation is blocked until the account has one.
  3. Enter a key name (1–80 characters).
  4. Choose an expiry: 30, 90, 180, or 365 days. Expiry is mandatory and can never exceed 365 days.
  5. Select the scopes. At least one is required, and scopes cannot be expanded after creation — create a new key instead.
  6. Copy the secret from the one-time reveal.
The environment is the environment of the Blank deployment you are signed in to; you cannot choose it.
Each account can hold at most 5 active keys per environment. Revoke an unused key before creating another.

​
Inspect a key

GET /me returns ApiIdentity and nothing else: Use it as a startup self-check: fail fast on boot if environment or scopes are not what your service expects.

​
Rotate a key

Rotate from Settings in the Blank app. Rotation issues a new secret with a new key ID and revokes the original; it does not extend an existing secret. You may set a new expiry at rotation time, still bounded to 365 days. Because rotation produces a new credential rather than overlapping secrets, the safe sequence is:
  1. Create the rotated key and copy the new secret.
  2. Write it to your secret manager.
  3. Roll your deployment so every process reads the new value.
  4. Confirm traffic on the new key ID via GET /me and your own logs.
Reading the credential through a function makes step 3 a config change rather than a redeploy:
Webhook signing secrets rotate differently — they support an explicit overlap window. See Webhooks.

​
Revoke a key

Revoke from Settings. Revocation takes effect for subsequent requests: the key immediately fails authentication with 401 invalid_api_key. Key creation, rotation, and revocation are all recorded as api_key.* audit events on the account. Revoke immediately if a secret is exposed in a log, a screenshot, a repository, a CI artifact, or a support ticket.

​
Handling the secret

  • Store it in a secret manager or environment variable. Never in source control, never in a client bundle, never in a container image layer.
  • Never log the credential. Log apiKeyId and X-Request-Id instead.
  • Give each service and each environment its own key so revocation is surgical.
  • Grant the narrowest scope set that works. A read-only integration should never hold predictions:write or webhooks:write.
  • Treat a one-time reveal as the only copy. There is no recovery path.
Never construct a BlankClient with an apiKey in browser or mobile code. The SDK throws in a browser runtime, and the API sends no Access-Control-Allow-Origin for authenticated operations, so the request would fail in the browser anyway. If a browser needs private data, proxy it through your own server.

​
Anonymous access

These operations require no key and are browser-reachable: token list and detail, market snapshot, candles, trades, holder stats, staking pool and leaderboard, presale list and detail, prediction rounds, round entries, standings, and the Solana manifest. They are rate-limited per IP and globally, and they prove nothing about who is calling. Never treat an anonymous read as authentication.

​
Authentication failures

invalid_api_key is deliberately undifferentiated so the API does not confirm whether a credential exists. Check the prefix, the environment, and the expiry, then rotate if all three look right.

​
Next

Scopes

The full scope catalogue and the operations each one unlocks.

Conventions

Rate limits, request IDs, retries, deadlines, and idempotency.