Nhost session API
Session management operations including token refresh, verification, and sign-out
OpenAPI Specification
openapi: 3.0.0
info:
version: 1.0.0
title: Nhost authentication session API
description: Comprehensive authentication service for managing user identities, sessions, and authentication methods
license:
name: MIT License
url: https://opensource.org/licenses/MIT
contact:
name: Nhost Support
email: support@nhost.io
url: https://nhost.io
servers:
- url: https://{subdomain}.auth.{region}.nhost.run/v1
description: Nhost Authentication API Server
tags:
- name: session
description: Session management operations including token refresh, verification, and sign-out
paths:
/signout:
post:
summary: Sign out
description: End the current user session by invalidating refresh tokens. Optionally sign out from all devices.
operationId: signOut
tags:
- session
security:
- BearerAuth: []
- {}
requestBody:
description: Sign-out options including refresh token and whether to sign out from all devices
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SignOutRequest'
responses:
'200':
description: Successfully signed out
content:
application/json:
schema:
$ref: '#/components/schemas/OKResponse'
default:
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: An error occurred while processing the request
/token:
post:
summary: Refresh access token
description: Generate a new JWT access token using a valid refresh token. The refresh token used will be revoked and a new one will be issued.
operationId: refreshToken
tags:
- session
requestBody:
description: Refresh token to exchange for a new access token
content:
application/json:
schema:
$ref: '#/components/schemas/RefreshTokenRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Session'
description: Access token successfully refreshed
default:
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: An error occurred while processing the request
/token/verify:
post:
summary: Verify JWT token
description: Verify the validity of a JWT access token. If no request body is provided, the Authorization header will be used for verification.
operationId: verifyToken
tags:
- session
security:
- BearerAuth: []
- {}
requestBody:
description: Optional JWT token to verify (if not provided, Authorization header will be used)
content:
application/json:
schema:
$ref: '#/components/schemas/VerifyTokenRequest'
responses:
'200':
content:
application/json:
schema:
type: string
example: OK
description: Valid JWT token
default:
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: An error occurred while processing the request
components:
schemas:
User:
type: object
description: User profile and account information
additionalProperties: false
properties:
avatarUrl:
type: string
description: URL to the user's profile picture
example: https://myapp.com/avatars/user123.jpg
createdAt:
format: date-time
type: string
description: Timestamp when the user account was created
example: '2023-01-15T12:34:56Z'
defaultRole:
example: user
type: string
description: Default authorization role for the user
displayName:
example: John Smith
type: string
description: User's display name
email:
description: User's email address
example: john.smith@nhost.io
format: email
type: string
emailVerified:
type: boolean
description: Whether the user's email has been verified
example: true
id:
description: Unique identifier for the user
example: 2c35b6f3-c4b9-48e3-978a-d4d0f1d42e24
pattern: \b[0-9a-f]{8}\b-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-\b[0-9a-f]{12}\b
type: string
isAnonymous:
type: boolean
description: Whether this is an anonymous user account
example: false
locale:
description: User's preferred locale (language code)
example: en
maxLength: 2
minLength: 2
type: string
metadata:
type: object
additionalProperties: true
description: Custom metadata associated with the user
example:
firstName: John
lastName: Smith
properties: {}
phoneNumber:
type: string
description: User's phone number
example: '+12025550123'
phoneNumberVerified:
type: boolean
description: Whether the user's phone number has been verified
example: false
roles:
example:
- user
- customer
type: array
description: List of roles assigned to the user
items:
type: string
activeMfaType:
type: string
description: Active MFA type for the user
nullable: true
required:
- avatarUrl
- createdAt
- defaultRole
- displayName
- emailVerified
- id
- isAnonymous
- locale
- metadata
- phoneNumberVerified
- roles
SignOutRequest:
type: object
properties:
refreshToken:
type: string
description: Refresh token for the current session
all:
type: boolean
default: false
description: Sign out from all connected devices
ErrorResponse:
type: object
description: Standardized error response
additionalProperties: false
properties:
status:
description: HTTP status error code
type: integer
example: 400
message:
description: Human-friendly error message
type: string
example: Invalid email format
error:
description: Error code identifying the specific application error
type: string
enum:
- default-role-must-be-in-allowed-roles
- disabled-endpoint
- disabled-user
- email-already-in-use
- email-already-verified
- forbidden-anonymous
- internal-server-error
- invalid-email-password
- invalid-request
- locale-not-allowed
- password-too-short
- password-in-hibp-database
- redirectTo-not-allowed
- role-not-allowed
- signup-disabled
- unverified-user
- user-not-anonymous
- invalid-pat
- invalid-refresh-token
- invalid-ticket
- disabled-mfa-totp
- no-totp-secret
- invalid-totp
- mfa-type-not-found
- totp-already-active
- invalid-state
- oauth-token-echange-failed
- oauth-profile-fetch-failed
- oauth-provider-error
- invalid-otp
- cannot-send-sms
required:
- status
- message
- error
Session:
type: object
description: User authentication session containing tokens and user information
additionalProperties: false
properties:
accessToken:
type: string
description: JWT token for authenticating API requests
example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
accessTokenExpiresIn:
type: integer
format: int64
description: Expiration time of the access token in seconds
example: 900
refreshTokenId:
description: Identifier for the refresh token
example: 2c35b6f3-c4b9-48e3-978a-d4d0f1d42e24
pattern: \b[0-9a-f]{8}\b-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-\b[0-9a-f]{12}\b
type: string
refreshToken:
description: Token used to refresh the access token
example: 2c35b6f3-c4b9-48e3-978a-d4d0f1d42e24
pattern: \b[0-9a-f]{8}\b-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-\b[0-9a-f]{12}\b
type: string
user:
$ref: '#/components/schemas/User'
required:
- accessToken
- accessTokenExpiresIn
- refreshToken
- refreshTokenId
OKResponse:
type: string
additionalProperties: false
enum:
- OK
RefreshTokenRequest:
type: object
description: Request to refresh an access token
additionalProperties: false
properties:
refreshToken:
description: Refresh token used to generate a new access token
example: 2c35b6f3-c4b9-48e3-978a-d4d0f1d42e24
pattern: \b[0-9a-f]{8}\b-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-\b[0-9a-f]{12}\b
type: string
required:
- refreshToken
VerifyTokenRequest:
type: object
additionalProperties: false
properties:
token:
type: string
description: JWT token to verify
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: Bearer authentication with JWT access token. Used to authenticate requests to protected endpoints.
BearerAuthElevated:
type: http
scheme: bearer
description: Bearer authentication that requires elevated permissions. Used for sensitive operations that may require additional security measures such as recent authentication. For details see https://docs.nhost.io/guides/auth/elevated-permissions