Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/metabase/metabase/llms.txt

Use this file to discover all available pages before exploring further.

The Session API handles user authentication, session management, and password reset flows. This API includes 7 endpoints.
For general authentication information, see the Authentication guide.

​
Create session

Authenticate with email and password to create a new session. 
POST /api/session

curl -X POST \
  https://your-metabase.com/api/session \
  -H 'Content-Type: application/json' \
  -d '{
    "username": "user@example.com",
    "password": "your-password"
  }'

​
Request body

​
username
string
required
User email address
​
password
string
required
User password

​
Response

​
id
string
Session token (UUID) to use for authentication
{
  "id": "38f4939c-ad7f-4cbe-ae54-30946daf8593"
}
Store the session token securely and include it in the X-Metabase-Session header for all subsequent API requests.

​
Delete session

Log out and invalidate the current session. 
DELETE /api/session

curl -X DELETE \
  https://your-metabase.com/api/session \
  -H 'X-Metabase-Session: SESSION_TOKEN'

​
Response

Returns 204 No Content on success.
After logout, the session token is invalidated and cannot be reused.

​
Get session properties

Get configuration and properties for the current session. 
GET /api/session/properties

curl -X GET \
  https://your-metabase.com/api/session/properties \
  -H 'X-Metabase-Session: SESSION_TOKEN'

​
Response

Returns session configuration including:
​
engines
object
Available database engines and drivers
​
version
object
Metabase version information
​
settings
object
Instance-level settings
​
has-user-setup
boolean
Whether initial setup is complete
​
setup-token
string
Setup token if setup is incomplete

​
Google OAuth

Authenticate using Google OAuth. 
POST /api/session/google_auth

curl -X POST \
  https://your-metabase.com/api/session/google_auth \
  -H 'Content-Type: application/json' \
  -d '{
    "token": "google-oauth-token"
  }'

​
Request body

​
token
string
required
Google OAuth ID token

​
Response

Returns a session token on successful authentication: 
{
  "id": "38f4939c-ad7f-4cbe-ae54-30946daf8593"
}
Google OAuth must be configured in instance settings for this endpoint to work.

​
Password verification

Verify a password without creating a new session. 
POST /api/session/password-check

curl -X POST \
  https://your-metabase.com/api/session/password-check \
  -H 'Content-Type: application/json' \
  -H 'X-Metabase-Session: SESSION_TOKEN' \
  -d '{
    "password": "current-password"
  }'

​
Request body

​
password
string
required
Password to verify for the current user

​
Response

​
valid
boolean
Whether the password is correct
{
  "valid": true
}
Requires an active session. Used to confirm user identity before sensitive operations like changing email or password.

​
Request password reset

Send a password reset email to a user. 
POST /api/session/forgot_password

curl -X POST \
  https://your-metabase.com/api/session/forgot_password \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "user@example.com"
  }'

​
Request body

​
email
string
required
Email address of the user requesting password reset

​
Response

Returns 200 OK on success (even if email doesn’t exist, for security).
The endpoint always returns success to prevent email enumeration attacks. The user will receive an email with reset instructions if the account exists.

​
Validate reset token

Check if a password reset token is valid. 
GET /api/session/password_reset_token_valid

curl -X GET \
  'https://your-metabase.com/api/session/password_reset_token_valid?token=RESET_TOKEN'

​
Query parameters

​
token
string
required
Password reset token from the email

​
Response

​
valid
boolean
Whether the token is valid and not expired
{
  "valid": true
}

​
Reset password

Reset a user’s password using a valid reset token. 
POST /api/session/reset_password

curl -X POST \
  https://your-metabase.com/api/session/reset_password \
  -H 'Content-Type: application/json' \
  -d '{
    "token": "reset-token-from-email",
    "password": "NewSecurePassword123!"
  }'

​
Request body

​
token
string
required
Password reset token from the email
​
password
string
required
New password (must meet password requirements)

​
Response

​
success
boolean
Whether the password was successfully reset
{
  "success": true
}
After successfully resetting the password, the user can log in with their new credentials.

​
Error codes

​
400 Bad Request
error
Invalid credentials, expired token, or password doesn’t meet requirements
​
401 Unauthorized
error
Invalid username or password
​
403 Forbidden
error
Account is deactivated or suspended
​
429 Too Many Requests
error
Too many login attempts. Please wait before trying again.