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 Metabase API uses session-based authentication. You need to create a session by providing valid credentials, then use the returned session token for subsequent API requests.

​
Create a session

To authenticate, send a POST request to the /api/session endpoint with your email and password.

​
Request

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

​
Parameters

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

​
Response

​
id
string
Session token to use for authentication
{
  "id": "38f4939c-ad7f-4cbe-ae54-30946daf8593"
}

​
Using the session token

Once you have a session token, include it in the X-Metabase-Session header for all subsequent API requests. 
curl -X GET \
  https://your-metabase.com/api/user/current \
  -H 'X-Metabase-Session: 38f4939c-ad7f-4cbe-ae54-30946daf8593'

​
Session properties

Get properties about the current session and authenticated user.

​
Request

GET /api/session/properties

curl -X GET \
  https://your-metabase.com/api/session/properties \
  -H 'X-Metabase-Session: 38f4939c-ad7f-4cbe-ae54-30946daf8593'

​
Response

Returns session configuration and user information including available features, settings, and user permissions.

​
Google OAuth authentication

Metabase supports Google OAuth for authentication when enabled.

​
Request

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"
  }'
​
token
string
required
Google OAuth token

​
Delete a session (logout)

To log out and invalidate a session token, send a DELETE request.

​
Request

DELETE /api/session

curl -X DELETE \
  https://your-metabase.com/api/session \
  -H 'X-Metabase-Session: 38f4939c-ad7f-4cbe-ae54-30946daf8593'

​
Response

Returns a 204 No Content status on success.

​
Password reset

​
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"
  }'
​
email
string
required
Email address of the user requesting password reset

​
Validate reset token

Check if a password reset token is valid. 
GET /api/session/password_reset_token_valid?token={token}
​
token
string
required
Password reset token

​
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",
    "password": "new-password"
  }'
​
token
string
required
Password reset token from email
​
password
string
required
New password

​
Password verification

Verify a password without creating a 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: 38f4939c-ad7f-4cbe-ae54-30946daf8593' \
  -d '{
    "password": "current-password"
  }'
​
password
string
required
Password to verify
Requires an active session. Used for confirming user identity before sensitive operations.

​
Best practices

Security recommendations:
  • Store session tokens securely (never in client-side code or version control)
  • Implement token refresh logic for long-running applications
  • Always use HTTPS for API requests
  • Invalidate sessions when they’re no longer needed
  • Use environment variables for credentials
Session tokens grant full access to your Metabase instance with the authenticated user’s permissions. Treat them like passwords.