Skip to main content
POST/gate/signin

Sign In

Authenticates a project-scoped end-user with email and password credentials and returns a Gate JWT plus refresh token on success.

When MFA is enrolled and required by project policy, the response carries mfa.required: true and the access token's mfa claim is "required"; the end-user must complete an MFA challenge before the token carries full authority.

Returns K9O_INVALID_CREDENTIALS (401) on credential mismatch; repeated failures trigger rate-limiting.

Parameters
projectSlug *path

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

It is unique within the org.

Request body
email *string <email>

The end user's email address.

Case does not matter.

password *string

The end user's password.

Responses
HTTPK9O CodeDescription
200Success
401K9O_INVALID_CREDENTIALSThe supplied email or password is incorrect.
401K9O_MFA_REQUIREDSign-in succeeded but an MFA challenge must be completed before a session is issued.
429K9O_RATE_LIMITEDToo many wrong passwords for this account: its password sign-in is locked for a while (15 minutes, then 1 hour, then 4 hours within a day). Every attempt during the lock gets this answer, the right password too; `recommendation.retryAfterSec` says when to try again. Passkey, one-time code, magic link and password reset still work.
502K9O_IDP_FEDERATION_FAILEDFederated sign-in via the configured identity provider returned an unprocessable response.
Response body (200)
data *any

Either session (signed in) or mfa (a code is needed first), never both.

One of: object
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.

or: object
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.

mfa *object

Present instead of session when the end user has a confirmed authenticator app: the sign-in needs a code first.

required *true

Always true: the end user has a confirmed authenticator app, so this sign-in needs a code before it gets a session.

challengeId *string

An opaque, single-use id for this sign-in (43 base64url characters).

Send it with a current code from the end user's authenticator app to POST /@{projectSlug}/gate/mfa/challenge, on the origin in resident.origin, to get the session.

A new sign-in by the same door replaces it, and it dies after 5 wrong codes.

expiresAt *string <date-time>

When the challenge expires, 5 minutes after it was issued.

After that the end user signs in again.

methodsAvailable *"totp"[]

The second factors that can answer this challenge.

Always ["totp"]: a time-based code from an authenticator app.

resident *object

Where the challenge lives.

region *string

The region that holds the end user and this challenge.

origin *string

That region's API origin.

Send the challenge answer here: no other region has the challenge.

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.signIn({
  email: '[email protected]',
  password: 'correct-horse-battery-staple'
})

Showing example in TypeScript

Request example
{
  "email": "[email protected]",
  "password": "correct-horse-battery-staple"
}
Response example (200)
{
  "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