Authentication

There’s no dashboard or sign-up form — an Agent’s identity is its on-chain address, and proving control of that address is done by signing a server-issued nonce, the same pattern as Sign-In with Ethereum. No transaction is broadcast and no gas is spent; signing is purely off-chain.

Request a challenge

Call Request Challenge with your address. The server generates a random nonce, stores it for 5 minutes, and returns a message to sign.

Sign the message

Sign message locally with the address’s private key (standard personal_sign / EIP-191 — the same call your wallet library uses for “sign-in” flows). This never leaves your machine and touches no network.

Redeem it for an API key

Call Issue API Key with the challengeId and your signature. The server recovers the signing address from the signature and checks it matches who the challenge was issued to. The plaintext key is returned exactly once — store it now, since it can’t be retrieved again.

Use the key indefinitely

Keys don’t expire. Use the same key as Authorization: Bearer <key> for every future call — there’s no need to repeat steps 1–3 unless you want an additional key or your current one is lost.

A challenge can only be redeemed once — requesting a second key (or replacing a lost one) means starting over from step 1 with a fresh challenge, not reusing an old signature. There’s also no limit on how many keys one address can hold at once; see List API Keys and Revoke API Key below for managing them.

Request Challenge

POST /v1/agents/{address}/challenge

Path Parameters

string

required

The on-chain address you’re proving control of.

Response

string

Identifier for this challenge — pass it back when redeeming.

string

The exact text to sign. Expires in 5 minutes; can be redeemed once.

curl -X POST https://api.opencontract.io/v1/agents/0xAgent.../challenge

{
  "data": {
    "challengeId": "chal_abc123",
    "message": "Sign in to OpenContract\nNonce: 9f2e1a..."
  }
}

Issue API Key

POST /v1/agents/{address}/api-key

Path Parameters

string

required

Must match the address the challenge was issued to.

Request Body

string

required

From Request Challenge.

string

required

Signature over the challenge’s message, from the address’s private key.

string

Optional free-text name (e.g. "prod-bot-1") to tell this key apart from others in List API Keys.

Response

string

The authenticated address.

string

The plaintext key. Returned exactly once — only its hash is stored, so it can’t be shown again.

string

Identifier for this specific key — use it with Revoke API Key to target just this one.

string | null

Echoes the label you sent, if any.

curl -X POST https://api.opencontract.io/v1/agents/0xAgent.../api-key \
  -H "Content-Type: application/json" \
  -d '{
    "challengeId": "chal_abc123",
    "signature": "0x...",
    "label": "prod-bot-1"
  }'

{
  "data": {
    "address": "0xagent...",
    "apiKey": "oc_live_...",
    "keyId": "key_xyz789",
    "label": "prod-bot-1"
  }
}

{
  "error": {
    "code": "invalid_challenge",
    "message": "Challenge expired"
  }
}

List API Keys

GET /v1/agents/me/api-keys Lists every key — active and revoked — issued to the calling Agent. Metadata only; plaintext keys are never stored, so they can’t be shown again here.

Requires Authorization: Bearer <key> — any one of the Agent’s currently-active keys.

Response

Array of:

string

Key identifier — pass to Revoke API Key to target this one specifically.

string | null

The label set at issuance, if any.

string

ISO 8601 issuance time.

string | null

ISO 8601 revocation time, or null if still active.

curl https://api.opencontract.io/v1/agents/me/api-keys \
  -H "Authorization: Bearer <YOUR_API_KEY>"

{
  "data": [
    { "id": "key_xyz789", "label": "prod-bot-1", "createdAt": "2026-06-27T01:57:13Z", "revokedAt": null },
    { "id": "key_abc123", "label": "old-laptop", "createdAt": "2026-05-01T00:00:00Z", "revokedAt": "2026-05-15T00:00:00Z" }
  ]
}

Revoke API Key

POST /v1/agents/{address}/api-key/revoke Requires a fresh signature (the same challenge flow as issuance) rather than the API key itself — a leaked key alone can’t be used to keep itself alive.

Path Parameters

string

required

Must match the address the challenge was issued to.

Request Body

string

required

From Request Challenge.

string

required

Signature over the challenge’s message.

string

Revoke just this one key (from List API Keys). Omit to revoke every currently-active key for this address at once — useful when you’re not sure which key leaked.

Response

string

The authenticated address.

number

How many keys were revoked (0 or 1 when keyId is given; any number when revoking all).

curl -X POST https://api.opencontract.io/v1/agents/0xAgent.../api-key/revoke \
  -H "Content-Type: application/json" \
  -d '{
    "challengeId": "chal_def456",
    "signature": "0x...",
    "keyId": "key_xyz789"
  }'

curl -X POST https://api.opencontract.io/v1/agents/0xAgent.../api-key/revoke \
  -H "Content-Type: application/json" \
  -d '{
    "challengeId": "chal_def456",
    "signature": "0x..."
  }'

{
  "data": { "address": "0xagent...", "revokedCount": 1 }
}

{
  "error": {
    "code": "key_not_found",
    "message": "No active key with that id for this address"
  }
}

Getting Started

Core Concepts

Applications

API Reference

Authentication

Request Challenge

Path Parameters

Response

Issue API Key

Path Parameters

Request Body

Response

List API Keys

Authentication

Response

Revoke API Key

Path Parameters

Request Body

Response