API reference

Credentials

Provision, verify, and revoke the ed25519 credential that is both your API identity and your account.

Your credential is your account. There is no separate account resource, no username, and no password.

POST /auth/provision

Creates a new ed25519 keypair and registers it as an active account. This is the only endpoint that requires no authentication, since you have nothing to sign with yet.

curl -X POST "$TESSERA_API/auth/provision"

Response — 201 Created

{
  "appID": "Aq3fZm9rLXRl",
  "appKey": "kR8vN2pQ...",
  "credential": "Aq3fZm9rLXRlc3QtY3JlZGVudGlhbC1oZXJlLW9r="
}

Field	Description
`appID`	A short, non-secret identifier derived from the public key. Safe to log, useful in support requests.
`appKey`	The private key. 64 bytes, base64url, unpadded. Returned exactly once and never recoverable.
`credential`	The public key. 32 bytes, base64url, padded. Your account identifier and the `credential` query parameter.

Store `appKey` before you store data

There is no recovery flow. We hold only the public half. If appKey is lost, every object under it becomes unreachable — to you and to us. It is also the account itself, so it cannot be rotated without re-registering your objects under a new credential.

Errors

Status	Body	Cause
`405`	`method not allowed`	Not a `POST`.
`429`	`{"error": "rate limited: max 5 keys per hour"}`	More than 5 provisions from one source address within an hour.
`500`	`{"error": "..."}`	Key generation failed.

The rate limit is per source address and honours X-Forwarded-For. If you need many credentials — one per tenant, say — request a bulk arrangement rather than working around the limit.

GET /auth/check

Verifies that a credential is provisioned, active, and that your signature is correct. The cheapest way to test a signing implementation.

curl -sD - -o /dev/null "$TESSERA_API/auth/check?$AUTH"

Response — 204 No Content on success. No body.

401 with a plain-text reason otherwise; see Authentication for the full list of reasons and what each one means.

DELETE /auth/revoke

Revokes a credential. Effective immediately — the next request using it fails.

curl -X DELETE "$TESSERA_API/auth/revoke?credential=$TARGET&$AUTH"

Parameter	Required	Description
`credential`	yes	The credential to revoke, padded base64url.

Response — 204 No Content.

Errors

Status	Body	Cause
`400`	`missing credential`	The `credential` parameter was absent.
`401`	(various)	The signing credential was not accepted.
`405`	`method not allowed`	Not a `DELETE`.

Revocation stops access, not storage

Revoking a credential stops authorisation. It does not delete your objects, and the storage contracts covering their shards remain funded until they expire. If you intend to remove data, delete the objects first and then revoke — in that order, because after revocation you can no longer issue the deletes.

Account state

Internally a credential is in one of four states. Only active authorises requests:

State	Behaviour
`provisioned`	Created but not yet activated. Requests are refused as `unknown credential`.
`active`	Normal operation.
`suspended`	Temporarily refused, for example for non-payment. Data is retained.
`revoked`	Permanently refused. The record is kept so the key cannot be re-provisioned.

A refused request returns 401 unknown credential regardless of which non-active state applies — the API does not distinguish, deliberately, since telling an unauthenticated caller why a key is refused is more useful to an attacker than to you.

Caps

Each credential carries caps for maximum stored bytes, daily read and write volume, and monthly spend. Requests that would exceed a storage cap are refused with 402 Payment Required:

{
  "error": "storage cap exceeded",
  "capBytes": 5497558138880,
  "incomingBytes": 62914560
}

Caps are set when the credential is provisioned for you as part of a plan. Self-provisioned credentials are created with the default plan limits. See Limits.