POST /v1/signup/verify

Call	POST /v1/signup/verify
Price	free
Scope	none (public endpoint)
Operation id	verifySignup

What it does

Exchange the token from the verification email for your organization, default project and first API key. The key secret is returned once; store it. Starter credits ($5) are granted. The token is single use. Free. No key needed.

Example request

Copy it as curl. Set VERDICT_API_KEY first; uuidgen makes a fresh Idempotency-Key.

Request

curl -X POST 'https://api.askverdict.io/v1/signup/verify' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "token": "Ex4mpleVerificationTokenFromTheEmailLink0001"
}'

Example response

201: The new organization and key.

201 response

{
  "org_id": "org_01JC3Z4Y8R9K2M5N7P1Q3S5T7V",
  "project_id": "prj_01JC3Z4Y8R9K2M5N7P1Q3S5T7V",
  "key": {
    "id": "key_01JC3Z4Y8R9K2M5N7P1Q3S5T7V",
    "project_id": "prj_01JC3Z4Y8R9K2M5N7P1Q3S5T7V",
    "name": "default",
    "environment": "live",
    "prefix": "vd_live_Ab12Cd",
    "scopes": [
      "decisions:write",
      "index:read",
      "outcomes:write"
    ],
    "status": "active",
    "rate_limit_per_minute": 600,
    "daily_spend_cap_usd": 25,
    "ip_allowlist": [],
    "expires_at": null,
    "last_used_at": null,
    "created_at": "2026-11-07T14:00:00Z",
    "secret": "vd_live_<shown-once>"
  },
  "starter_credit_usd": 5,
  "balance_usd": 5
}

Parameters

Name	In	Type	Required	Description
idempotency-key	header	string (uuid)	yes	A UUID you generate per logical request. Required on every POST. Repeating it within 24 hours returns the stored response and bills nothing; reusing it with a different body returns 409 idempotency_conflict.

Request body

Schema VerifySignupRequest. The verification token.

Field	Type	Required	Description
token	string	yes	The token from the verification link.

Response fields (201)

Schema VerifySignupResponse.

Field	Type	Required	Description
org_id	string	yes	The new organization.
project_id	string	yes	Its default project.
key	CreatedApiKey	yes	A new API key with its secret (shown once).
key.id	string	yes	The key id.
key.project_id	string	yes	Project the key belongs to.
key.name	string	yes	Name.
key.environment	enum: “live”, “test”	yes	live or test.
key.prefix	string	yes	The key’s first characters, to recognize it.
key.scopes	array of enum: “decisions:write”, “index:read”, “outcomes:write”, “watches:manage”, “vendors:call”, “account:read”, “account:manage”, “keys:manage”	yes	Scopes granted.
key.status	enum: “active”, “rotating”, “revoked”, “expired”	yes	Lifecycle status.
key.rate_limit_per_minute	integer	yes	Requests per minute allowed.
key.daily_spend_cap_usd	number or null	yes	Daily spend cap, or null for none. US dollars, up to 6 decimals.
key.ip_allowlist	array of string	yes	CIDR blocks the key may be used from; empty means anywhere.
key.expires_at	string or null (date-time)	yes	Expiry, or null for none.
key.last_used_at	string or null (date-time)	yes	Last successful use, or null.
key.created_at	string (date-time)	yes	When the key was created.
key.secret	string	yes	The API key: vd_live_ or vd_test_ plus a base62 body. Shown once; store it now.
starter_credit_usd	number	yes	Starter credits granted. US dollars, up to 6 decimals.
balance_usd	number	yes	Balance after the grant. US dollars, up to 6 decimals.

Errors

Errors are RFC 9457 problem details and are never billed. Branch on type. See Errors.

Status	Meaning
400	Invalid request: malformed JSON, an unknown field, a failed constraint or a size limit (invalid_request).
404	The resource does not exist in this organization (not_found).
409	The Idempotency-Key was reused with a different request, or the first request is still running (idempotency_conflict).
429	Rate limited (rate_limited). Wait Retry-After seconds.
500	Unexpected server error (internal). Not billed; retry with the same Idempotency-Key.

Try it

Open the interactive reference to send this request from the browser. The full document is at /openapi.json.