Download OpenAPI specification:Download
The Authentication API handles all end-user identity operations for applications built on Protekt. You can perform signup, login, passwordless flows, SSO, MFA, and session management. All requests require a project API key via the X-Protekt-Key header.
Register a new user with email and password. Protekt hashes and stores credentials internally. Optionally triggers an email verification flow.
| email required | string <email> |
| password required | string <password> >= 8 characters |
object Arbitrary key-value pairs stored alongside the user profile | |
| send_verification | boolean If true, sends an email verification link. Defaults to project setting. |
{- "email": "user@example.com",
- "password": "pa$$word",
- "metadata": { },
- "send_verification": true
}{- "access_token": "eyJhbGci...",
- "refresh_token": "rt_xYz...",
- "expires_in": 3600,
- "token_type": "Bearer",
- "user": {
- "id": "usr_9klabc",
- "email": "user@example.com",
- "email_verified": true,
- "mfa_enabled": true,
- "mfa_methods": [
- "totp"
], - "metadata": { },
- "disabled": true,
- "created_at": "2019-08-24T14:15:22Z",
- "last_login_at": "2019-08-24T14:15:22Z"
}
}Authenticate a user with email and password. Returns a signed JWT and refresh token on success.
If MFA is required, returns a mfa_required challenge response instead of tokens.
| email required | string <email> |
| password required | string <password> |
{- "email": "user@example.com",
- "password": "pa$$word"
}{- "access_token": "eyJhbGci...",
- "refresh_token": "rt_xYz...",
- "expires_in": 3600,
- "token_type": "Bearer",
- "user": {
- "id": "usr_9klabc",
- "email": "user@example.com",
- "email_verified": true,
- "mfa_enabled": true,
- "mfa_methods": [
- "totp"
], - "metadata": { },
- "disabled": true,
- "created_at": "2019-08-24T14:15:22Z",
- "last_login_at": "2019-08-24T14:15:22Z"
}
}Obtain a new access token using a valid refresh token. The old refresh token is rotated and invalidated on each successful call.
| refresh_token required | string |
{- "refresh_token": "rt_xYz..."
}{- "access_token": "string",
- "refresh_token": "string",
- "expires_in": 3600
}Validate an access token and return its decoded claims. Use this on your backend to confirm a user is authenticated before granting access to protected resources.
| token required | string The JWT access token to verify |
{- "token": "string"
}{- "valid": true,
- "claims": {
- "sub": "usr_9klabc",
- "email": "user@example.com",
- "iat": 0,
- "exp": 0,
- "project_id": "string"
}
}Immediately invalidate a specific access or refresh token without ending the entire session.
| token required | string The token to revoke |
{- "token": "string"
}{- "revoked": true
}Trigger a password reset email. Protekt sends a one-time reset link to the user's registered email, expiring after 15 minutes.
Always returns 200 OK regardless of whether the email exists, to prevent user enumeration attacks.
| email required | string <email> |
{- "email": "user@example.com"
}{- "message": "If that email is registered, a reset link has been sent."
}Complete the password reset flow by submitting the reset token (from the email link) and the new password.
| reset_token required | string One-time reset token from the email link |
| new_password required | string <password> >= 8 characters |
{- "reset_token": "string",
- "new_password": "pa$$word"
}{- "message": "Password has been reset successfully."
}Allow an authenticated user to change their own password by providing their current password and the desired new password.
| current_password required | string <password> |
| new_password required | string <password> >= 8 characters |
{- "current_password": "pa$$word",
- "new_password": "pa$$word"
}{- "message": "Password changed successfully."
}Send a one-time passcode to a user's email or phone for passwordless authentication or as a second factor. OTPs expire after 10 minutes.
string <email> Required if phone is not provided | |
| phone | string E.164 format. Required if email is not provided |
| channel | string Default: "email" Enum: "email" "sms" |
{- "email": "user@example.com",
- "phone": "+2348012345678",
- "channel": "email"
}{- "message": "OTP sent",
- "expires_in": 600
}Verify an OTP code sent via POST /auth/otp/send. Returns a JWT and refresh token on success.
string <email> Required if OTP was sent to an email | |
| phone | string Required if OTP was sent to a phone number |
| otp required | string The 6-digit OTP |
{- "email": "user@example.com",
- "phone": "string",
- "otp": "482910"
}{- "access_token": "eyJhbGci...",
- "refresh_token": "rt_xYz...",
- "expires_in": 3600,
- "token_type": "Bearer",
- "user": {
- "id": "usr_9klabc",
- "email": "user@example.com",
- "email_verified": true,
- "mfa_enabled": true,
- "mfa_methods": [
- "totp"
], - "metadata": { },
- "disabled": true,
- "created_at": "2019-08-24T14:15:22Z",
- "last_login_at": "2019-08-24T14:15:22Z"
}
}Send a magic link to the user's email. When clicked, the link authenticates the user without a password. The link expires after 15 minutes and is single-use.
| email required | string <email> |
| redirect_url | string <uri> Override the project's default redirect URL for this request |
{- "email": "user@example.com",
}{- "message": "Magic link sent",
- "expires_in": 900
}Verify a magic link token extracted from the URL after the user clicks the emailed link. Returns a JWT and refresh token on success.
| token required | string The magic link token from the email URL parameter |
{- "token": "string"
}{- "access_token": "eyJhbGci...",
- "refresh_token": "rt_xYz...",
- "expires_in": 3600,
- "token_type": "Bearer",
- "user": {
- "id": "usr_9klabc",
- "email": "user@example.com",
- "email_verified": true,
- "mfa_enabled": true,
- "mfa_methods": [
- "totp"
], - "metadata": { },
- "disabled": true,
- "created_at": "2019-08-24T14:15:22Z",
- "last_login_at": "2019-08-24T14:15:22Z"
}
}The redirect target for the SSO provider after authentication. Protekt exchanges the authorization code for a session and redirects with tokens.
Register https://auth.protekt.io/v1/auth/sso/callback as the callback URL in your IdP configuration.
| code required | string Authorization code from the IdP |
| state | string The state value originally passed to /auth/sso/authorize |
Begin enrolling a user in MFA. Enrollment is not finalized until the user verifies a code via POST /auth/mfa/verify.
| method required | string Enum: "totp" "sms" |
| phone | string E.164 phone number. Required when method is sms. |
{- "method": "totp",
- "phone": "string"
}{- "method": "totp",
- "totp_uri": "otpauth://totp/Protekt:user@example.com?secret=BASE32SECRET&issuer=Protekt",
- "qr_code": "data:image/png;base64,..."
}Verify an MFA code. Used both to finalize MFA enrollment and to complete a login challenge. On a successful login challenge, returns a full JWT session.
| mfa_token | string Temporary MFA challenge token from POST /auth/login. Required during login. |
| code required | string The 6-digit TOTP or SMS code |
{- "mfa_token": "mfa_tmp_abc...",
- "code": "482910"
}{- "access_token": "eyJhbGci...",
- "refresh_token": "rt_xYz...",
- "expires_in": 3600,
- "token_type": "Bearer",
- "user": {
- "id": "usr_9klabc",
- "email": "user@example.com",
- "email_verified": true,
- "mfa_enabled": true,
- "mfa_methods": [
- "totp"
], - "metadata": { },
- "disabled": true,
- "created_at": "2019-08-24T14:15:22Z",
- "last_login_at": "2019-08-24T14:15:22Z"
}
}Remove an MFA method from a user's account. Requires a valid user access token.
Returns 403 if the project enforces MFA (mfa_required: true).
| method required | string Enum: "totp" "sms" |
{- "method": "totp"
}{- "unenrolled": true
}List all users registered within a project. Intended for admin/backend use. Requires an API key with users:read scope.
| limit | integer <= 100 Default: 20 Max number of results per page |
| cursor | string Pagination cursor from the previous response |
| search | string Filter by email (partial match) |
{- "data": [
- {
- "id": "usr_9klabc",
- "email": "user@example.com",
- "email_verified": true,
- "mfa_enabled": true,
- "mfa_methods": [
- "totp"
], - "metadata": { },
- "disabled": true,
- "created_at": "2019-08-24T14:15:22Z",
- "last_login_at": "2019-08-24T14:15:22Z"
}
], - "next_cursor": "cur_abc123",
- "has_more": true
}Retrieve a user's full profile by ID, including metadata, MFA status, and account state.
| id required | string The unique user ID (for example, usr_9klabc) |
{- "id": "usr_9klabc",
- "email": "user@example.com",
- "email_verified": true,
- "mfa_enabled": true,
- "mfa_methods": [
- "totp"
], - "metadata": { },
- "disabled": true,
- "created_at": "2019-08-24T14:15:22Z",
- "last_login_at": "2019-08-24T14:15:22Z"
}Update a user's profile or metadata. Admins can update any user; users can update their own profile via their access token.
| id required | string The unique user ID (for example, usr_9klabc) |
string <email> New email address. Triggers a re-verification email. | |
object Merged (not replaced) into existing metadata | |
| disabled | boolean Set to true to lock the account. Admin only. |
{- "email": "user@example.com",
- "metadata": { },
- "disabled": true
}{- "id": "usr_9klabc",
- "email": "user@example.com",
- "email_verified": true,
- "mfa_enabled": true,
- "mfa_methods": [
- "totp"
], - "metadata": { },
- "disabled": true,
- "created_at": "2019-08-24T14:15:22Z",
- "last_login_at": "2019-08-24T14:15:22Z"
}Permanently delete a user and all their sessions, tokens, and stored data from the project. This is irreversible.
| id required | string The unique user ID (for example, usr_9klabc) |
{- "deleted": true,
- "id": "usr_9klabc"
}List all active sessions for the currently authenticated user, including device, IP address, and last active time.
{- "data": [
- {
- "id": "sess_kl8abc",
- "ip_address": "197.210.xx.xx",
- "user_agent": "string",
- "created_at": "2019-08-24T14:15:22Z",
- "last_active_at": "2019-08-24T14:15:22Z",
- "is_current": true
}
]
}Revoke all active sessions for the current user — "sign out everywhere". The current session is also terminated unless keep_current is true.
| keep_current | boolean Default: false If true, the current session is preserved |
{- "keep_current": false
}{- "revoked_count": 4
}Terminate a specific session by ID. Useful for "sign out this device" functionality.
| id required | string The unique session ID (for example, sess_kl8abc) |
{- "revoked": true,
- "session_id": "sess_kl8abc"
}