Guest Signup

Create a Kicbak account for a guest from their email alone. The account is attributed to you, has no password, and activates when the guest gives you the six-digit code we email them.

POSThttps://kicbak.co/api/third-party/v1/kicbak/signup

Authentication

Every request needs a bearer token in the Authorization header. Unlike the invite and wallet endpoints, this one accepts organisation-owned AND user-owned credentials: whoever the credential belongs to is who the new account is attributed to. Nothing in the body can change that.

Headers

Field	Type	Required	Description
Authorization	string	required	Bearer token obtained from POST /api/third-party/v1/auth/token, e.g. "Bearer eyJhbGci...".
Content-Type	string	required	application/json

Request body

Field	Type	Required	Description
email	string	required	The guest's email address. This is their whole identity: no password is set, and the six-digit code that activates the account goes here.
name	string	optional	Display name, up to 120 characters. When omitted the generated username is used. The guest can change it later.

How it fits together

1) POST /kicbak/signup — the account exists, PENDING, no password, attributed to you; a code is emailed to the guest. 2) Show a code field on your site. A PENDING account cannot hold rewards, so nothing is paid yet. 3) POST /kicbak/signup/verify with the code — the account becomes ACTIVE with a wallet, and the signup referral is credited to you. 4) The guest signs in to kicbak.co with an emailed code, no password, and can set one later if they want.

Sandbox credentials get the code in the response

A sandbox credential sends no email, so the response carries verificationCode and codeDelivery is "response". A production credential emails the guest, codeDelivery is "email", and the code never appears in the response.

Idempotent on the email

Signing up an address that is still pending is not an error: you get replay: true, the same account, and a fresh code is issued — which is also how you resend a code the guest lost. An address that already has a working account is refused with EMAIL_ALREADY_REGISTERED; you cannot adopt an existing member by signing them up.

Code examples

bash

curl -X POST "https://kicbak.co/api/third-party/v1/kicbak/signup" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "email": "ada@example.com", "name": "Ada Lovelace" }'

Responses

Every response is JSON with a status field (1 success, 0 failure). Failures also carry a code your error handler can branch on — it never changes if we reword message.

json

{
  "status": 1,
  "message": "Account created. A verification code has been issued.",
  "data": {
    "email": "ada@example.com",
    "username": "ada",
    "status": "PENDING",
    "codeExpiresInMinutes": 15,
    "codeDelivery": "email"
  }
}

Error reference

Status	Code	Meaning
400	—	A body field is missing or malformed. The message names the field.
409	EMAIL_ALREADY_REGISTERED	The email already has a working Kicbak account. The guest should sign in instead — Kicbak offers an emailed sign-in code, so no password is needed.
401	UNAUTHORIZED	No readable credential, or a token that doesn't decode/validate.
401	TOKEN_EXPIRED	Token aged out. Re-exchange the same client_key/client_secret and retry.
401	CREDENTIAL_ROTATED	This token was minted under a secret that has since been rotated. Exchange your new secret.
401	CREDENTIAL_EXPIRED	The credential itself is past its own expiry — re-exchanging will not help; request a new credential.
401	CLIENT_INACTIVE	The client has been deactivated.
503	SANDBOX_UNAVAILABLE	You are using a sandbox credential and the sandbox environment is temporarily unavailable on our side. Retry shortly; production credentials are unaffected.
429	—	More than 100 signups in an hour from this client.
500	INTERNAL_ERROR	Unexpected server error. Safe to retry: signup is idempotent on the email.

What this endpoint never tells you

Whether an address is a Kicbak member before you try. The 409 answers that only for an address the guest just typed into your own form. Do not use it to probe a list; it is rate limited per client for exactly that reason.