User signup, signin, and token management endpoints.
openapi: 3.1.0
info:
title: Supabase Auth Admin Authentication API
description: The Supabase Auth API (based on GoTrue) is a JWT-based API for managing users and issuing access tokens. It provides endpoints for user signup, signin with email/password, magic links, one-time passwords, OAuth social login, token refresh, user management, multi-factor authentication, and SAML-based single sign-on. When deployed on Supabase, the server requires an apikey header containing a valid Supabase-issued API key.
version: 2.0.0
contact:
name: Supabase Support
url: https://supabase.com/support
termsOfService: https://supabase.com/terms
servers:
- url: https://{project_ref}.supabase.co/auth/v1
description: Supabase Project Auth Server
variables:
project_ref:
description: Your Supabase project reference ID
default: your-project-ref
security:
- apiKeyAuth: []
tags:
- name: Authentication
description: User signup, signin, and token management endpoints.
paths:
/signup:
post:
operationId: signUp
summary: Sign up a new user
description: Creates a new user account with email and password, or phone and password. Returns the user object and session tokens. A confirmation email or SMS may be sent depending on project configuration.
tags:
- Authentication
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SignUpRequest'
responses:
'200':
description: User created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/AuthResponse'
'400':
description: Bad request - invalid email or password
'422':
description: Unprocessable entity - user already exists
/token:
post:
operationId: signIn
summary: Sign in with credentials
description: Authenticates a user with their credentials and returns a session including access and refresh tokens. The grant_type parameter determines the authentication method.
tags:
- Authentication
parameters:
- name: grant_type
in: query
required: true
description: The type of authentication grant to use.
schema:
type: string
enum:
- password
- refresh_token
- id_token
- pkce
requestBody:
required: true
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/PasswordGrantRequest'
- $ref: '#/components/schemas/RefreshTokenGrantRequest'
- $ref: '#/components/schemas/IdTokenGrantRequest'
responses:
'200':
description: Authentication successful
content:
application/json:
schema:
$ref: '#/components/schemas/AuthResponse'
'400':
description: Bad request - invalid credentials or grant type
'401':
description: Invalid login credentials
/otp:
post:
operationId: sendOtp
summary: Send a one-time password
description: Sends a one-time password to the specified email or phone number. If the email template uses a confirmation URL variable, a magic link is sent instead. The OTP can be verified using the /verify endpoint.
tags:
- Authentication
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/OtpRequest'
responses:
'200':
description: OTP sent successfully
'400':
description: Bad request
'429':
description: Rate limit exceeded
/magiclink:
post:
operationId: sendMagicLink
summary: Send a magic link
description: Sends a magic link email to the specified address for passwordless authentication. The user clicks the link to be authenticated.
tags:
- Authentication
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- email
properties:
email:
type: string
format: email
description: Email address to send the magic link to
responses:
'200':
description: Magic link sent successfully
'400':
description: Bad request
'429':
description: Rate limit exceeded
/recover:
post:
operationId: recoverPassword
summary: Send password recovery email
description: Sends a password recovery email to the specified address containing a link that allows the user to reset their password.
tags:
- Authentication
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- email
properties:
email:
type: string
format: email
description: Email address for password recovery
responses:
'200':
description: Recovery email sent
'400':
description: Bad request
'429':
description: Rate limit exceeded
/verify:
post:
operationId: verifyOtp
summary: Verify an OTP or token hash
description: Verifies a one-time password or token hash received via email or SMS. Supports different verification types including signup, recovery, invite, magiclink, email_change, and phone_change.
tags:
- Authentication
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/VerifyOtpRequest'
responses:
'200':
description: Verification successful
content:
application/json:
schema:
$ref: '#/components/schemas/AuthResponse'
'400':
description: Bad request - invalid or expired OTP
get:
operationId: verifyOtpRedirect
summary: Verify OTP via redirect
description: Verifies a token hash from a magic link or email confirmation redirect. This endpoint is typically called by clicking the link in the email.
tags:
- Authentication
parameters:
- name: token_hash
in: query
required: true
schema:
type: string
description: The token hash from the email link
- name: type
in: query
required: true
schema:
type: string
enum:
- signup
- recovery
- invite
- magiclink
- email_change
description: Type of verification
- name: redirect_to
in: query
schema:
type: string
format: uri
description: URL to redirect to after verification
responses:
'303':
description: Redirect to application with tokens
'400':
description: Invalid or expired token
/logout:
post:
operationId: signOut
summary: Sign out a user
description: Invalidates the user's current session and refresh token. Requires a valid access token in the Authorization header.
tags:
- Authentication
parameters:
- name: scope
in: query
schema:
type: string
enum:
- local
- global
- others
description: Scope of logout. Local revokes only the current session, global revokes all sessions, others revokes all other sessions.
security:
- bearerAuth: []
responses:
'204':
description: Successfully signed out
'401':
description: Unauthorized - invalid or missing token
components:
schemas:
User:
type: object
properties:
id:
type: string
format: uuid
description: Unique user identifier
aud:
type: string
description: Audience claim
role:
type: string
description: User role
email:
type: string
format: email
description: User email address
email_confirmed_at:
type: string
format: date-time
description: Timestamp when email was confirmed
phone:
type: string
description: User phone number
phone_confirmed_at:
type: string
format: date-time
description: Timestamp when phone was confirmed
confirmed_at:
type: string
format: date-time
description: Timestamp when user was confirmed
last_sign_in_at:
type: string
format: date-time
description: Timestamp of last sign-in
app_metadata:
type: object
properties:
provider:
type: string
description: Primary authentication provider
providers:
type: array
items:
type: string
description: List of linked authentication providers
description: Application-level metadata
user_metadata:
type: object
description: Custom user metadata
identities:
type: array
items:
$ref: '#/components/schemas/Identity'
description: Linked identity providers
factors:
type: array
items:
$ref: '#/components/schemas/MfaFactor'
description: Enrolled MFA factors
created_at:
type: string
format: date-time
description: Timestamp when user was created
updated_at:
type: string
format: date-time
description: Timestamp when user was last updated
AuthResponse:
type: object
properties:
access_token:
type: string
description: JWT access token for authenticating API requests
token_type:
type: string
description: Token type, always bearer
enum:
- bearer
expires_in:
type: integer
description: Number of seconds until the access token expires
expires_at:
type: integer
description: Unix timestamp when the access token expires
refresh_token:
type: string
description: Token used to obtain a new access token
user:
$ref: '#/components/schemas/User'
RefreshTokenGrantRequest:
type: object
required:
- refresh_token
properties:
refresh_token:
type: string
description: Refresh token from a previous authentication
IdTokenGrantRequest:
type: object
required:
- provider
- id_token
properties:
provider:
type: string
description: OAuth provider that issued the ID token
enum:
- google
- apple
- azure
- facebook
id_token:
type: string
description: ID token from the OAuth provider
nonce:
type: string
description: Nonce used during token generation
MfaFactor:
type: object
properties:
id:
type: string
format: uuid
description: Unique factor identifier
friendly_name:
type: string
description: Human-readable name for the factor
factor_type:
type: string
description: Type of MFA factor
enum:
- totp
status:
type: string
description: Factor status
enum:
- verified
- unverified
created_at:
type: string
format: date-time
description: Timestamp when factor was created
updated_at:
type: string
format: date-time
description: Timestamp when factor was last updated
Identity:
type: object
properties:
id:
type: string
description: Unique identity identifier
user_id:
type: string
format: uuid
description: ID of the associated user
identity_data:
type: object
description: Data from the identity provider
provider:
type: string
description: Identity provider name
last_sign_in_at:
type: string
format: date-time
description: Timestamp of last sign-in with this identity
created_at:
type: string
format: date-time
description: Timestamp when identity was linked
updated_at:
type: string
format: date-time
description: Timestamp when identity was last updated
PasswordGrantRequest:
type: object
required:
- password
properties:
email:
type: string
format: email
description: User email address
phone:
type: string
description: User phone number
password:
type: string
description: User password
SignUpRequest:
type: object
properties:
email:
type: string
format: email
description: User email address
phone:
type: string
description: User phone number in E.164 format
password:
type: string
description: User password
minLength: 6
data:
type: object
description: Custom user metadata
gotrue_meta_security:
type: object
properties:
captcha_token:
type: string
description: Captcha verification token
VerifyOtpRequest:
type: object
required:
- type
properties:
type:
type: string
description: Type of verification
enum:
- signup
- recovery
- invite
- magiclink
- email_change
- phone_change
- sms
- email
token:
type: string
description: OTP code to verify
token_hash:
type: string
description: Token hash from the email link
email:
type: string
format: email
description: Email address the OTP was sent to
phone:
type: string
description: Phone number the OTP was sent to
redirect_to:
type: string
format: uri
description: URL to redirect to after verification
OtpRequest:
type: object
properties:
email:
type: string
format: email
description: Email address to send OTP to
phone:
type: string
description: Phone number to send OTP to
create_user:
type: boolean
description: Whether to create a new user if one does not exist
default: true
securitySchemes:
apiKeyAuth:
type: apiKey
in: header
name: apikey
description: Supabase project API key (anon key for public operations, service_role key for admin operations).
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: JWT access token obtained from a successful authentication.
externalDocs:
description: Supabase Auth Documentation
url: https://supabase.com/docs/guides/auth