Skip to main content
POST/gate/signup

Sign Up

Creates a new end-user account on the project using email and password credentials.

On success, an eu_-prefixed end-user record is created and a project-scoped Gate JWT plus refresh token are returned.

This endpoint is app-layer-unauthenticated (reachable before any end-user JWT exists); the Free tier enforces a 50,000 MAU cap at the gateway.

Parameters
projectSlug *path

The project's slug: the path segment after @.

It is unique within the org.

Request body
email *string <email>

The new end user's email address.

It is stored in lower case and must not already be registered in this project.

password *string

The new password, at least 12 characters.

A password found in known data breaches is refused.

displayNamestring

A display name, 1 to 128 characters.

It is validated but not stored.

Responses
HTTPK9O CodeDescription
201Created
400K9O_INVALID_REQUEST_SHAPEThe supplied password is shorter than the minimum length required by the request schema.
400K9O_PASSWORD_COMPROMISEDThe new password appears in a known data breach at or above the project's threshold (the project's have-i-been-pwned install, with its Gate block on). Choose a different password; context is empty.
409K9O_EMAIL_ALREADY_REGISTEREDAn account with this email address already exists.
502K9O_IDP_FEDERATION_FAILEDFederated sign-up via the configured identity provider failed during the provisioning flow.
Response body (201)
data *object

The new end user, already signed in.

user *object

The end user.

id *string

The end user's id (eu_...).

email *string

The end user's email address.

An address given at sign-up is stored in lower case.

status *"active" | "locked" | "deleted"

The account's status.

A successful response always carries active: a locked or deleted account cannot sign in.

createdAt *string <date-time>

When the end user signed up.

updatedAt *any

When the account record last changed, or null if it never has.

One of: string <date-time>
or: null
lastSigninAt *any

When the end user last signed in with a password, or null if they never have (for example straight after sign-up).

One of: string <date-time>
or: null
roles *string[]

The end user's platform role.

Always ["PROJECT_END_USER"].

Roles you grant through end-user role grants are not listed here.

groups *string[]

Always an empty array in this response.

The end user's group names are carried in the access token's groups claim.

session *object

The tokens for the new session.

Keep the refresh token for POST /@{projectSlug}/gate/refresh and send the access token on API calls.

accessToken *string

A signed JWT that authenticates the end user to this project's API.

Send it as Authorization: Bearer <accessToken>.

Its subject (sub) is the end user's id (eu_...), its audience (aud) is the project id (proj_...), and its issuer is the API origin of the region that holds the end user.

It lives for the project's end-user access token lifetime: 30 minutes by default, settable from 5 to 60 minutes. expiresAt is when it expires.

It cannot be revoked early: signing out or revoking sessions stops the next refresh, but a token already issued stays valid until expiresAt.

refreshToken *string

An opaque secret (43 base64url characters) that gets a new access token from POST /@{projectSlug}/gate/refresh.

Store it securely and never send it anywhere else.

It is single use: every refresh returns a new refresh token, and sending the one it replaced a second time ends the whole session.

It stops working when the session ends: on sign-out, a password reset, a revoke-all, or when the project's session limits are reached (by default 30 days without a refresh, or 90 days after sign-in, whichever comes first).

expiresAt *string <date-time>

When accessToken expires.

Refresh before this time to keep the end user signed in.

meta *any

Request metadata: cost, timing and the request and trace ids.

TypeScript
// const k9o = new K9o({ orgSlug: 'playground', projectSlug: 'storefront', apiKey: 'k9o_…' })
const { data } = await k9o.gate.signUp({
  email: '[email protected]',
  password: 'correct-horse-battery-staple'
})

Showing example in TypeScript

Request example
{
  "email": "[email protected]",
  "password": "correct-horse-battery-staple"
}
Response example (201)
{
  "data": {
    "user": {
      "id": "string",
      "email": "string",
      "status": "active",
      "createdAt": "string",
      "updatedAt": "string",
      "lastSigninAt": "string",
      "roles": [
        "string"
      ],
      "groups": [
        "string"
      ]
    },
    "session": {
      "accessToken": "string",
      "refreshToken": "string",
      "expiresAt": "string"
    }
  }
}

More in Sign-in & Sessions