Skip to main content

Authentication API

These endpoints handle user authentication, account creation, token management, and password operations.

Log in​

Authenticate with email and password to receive JWT access and refresh tokens.

POST /api/v1/auth/login

Request body​

FieldTypeRequiredDescription
usernamestringYesYour email address
passwordstringYesYour password

Example​

curl -X POST https://your-tms-instance.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "[email protected]",
    "password": "SecurePassword123!"
  }'

Response 200 OK​

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer",
  "expires_in": 1800
}

The access_token expires after 30 minutes (1800 seconds). Use the refresh_token to get a new access token without re-entering credentials.

tip

Store the access token and include it in all subsequent requests:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Register a new account​

Create a new user account.

POST /api/v1/auth/register

Request body​

FieldTypeRequiredDescription
emailstringYesEmail address
usernamestringYesUnique username
passwordstringYesPassword (min 8 characters)
full_namestringYesFull name

Example​

curl -X POST https://your-tms-instance.com/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "username": "janesmith",
    "password": "SecurePassword123!",
    "full_name": "Jane Smith"
  }'

Response 201 Created​

{
  "id": 1,
  "email": "[email protected]",
  "username": "janesmith",
  "full_name": "Jane Smith",
  "is_active": true,
  "is_verified": false,
  "created_at": "2025-11-15T10:00:00Z"
}
info

New accounts are created with is_verified: false. The user will receive a verification email. Some organizations may require admin approval before the account is active.

Refresh an access token​

Exchange a valid refresh token for a new access token without re-entering credentials.

POST /api/v1/auth/refresh

Request body​

FieldTypeRequiredDescription
refresh_tokenstringYesThe refresh token from login

Example​

curl -X POST https://your-tms-instance.com/api/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "eyJhbGciOiJIUzI1NiIs..."
  }'

Response 200 OK​

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer",
  "expires_in": 1800
}

Get current user profile​

Retrieve information about the currently authenticated user.

GET /api/v1/auth/me

Requires: Bearer token

Example​

curl https://your-tms-instance.com/api/v1/auth/me \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Response 200 OK​

{
  "id": 1,
  "email": "[email protected]",
  "username": "janesmith",
  "full_name": "Jane Smith",
  "is_active": true,
  "is_verified": true,
  "role": "admin",
  "organization": {
    "id": 1,
    "name": "Acme Corp"
  },
  "created_at": "2025-11-15T10:00:00Z"
}

Request a password reset​

Send a password reset link to the user's email address.

POST /api/v1/auth/password-reset

Request body​

FieldTypeRequiredDescription
emailstringYesThe account email address

Example​

curl -X POST https://your-tms-instance.com/api/v1/auth/password-reset \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]"
  }'

Response 200 OK​

{
  "message": "Password reset email sent"
}
info

For security, this endpoint always returns 200 OK even if the email is not associated with an account. This prevents email enumeration.

Confirm password reset​

Set a new password using the token received via email.

POST /api/v1/auth/password-reset/confirm

Request body​

FieldTypeRequiredDescription
tokenstringYesReset token from the email link
new_passwordstringYesNew password (min 8 characters)

Example​

curl -X POST https://your-tms-instance.com/api/v1/auth/password-reset/confirm \
  -H "Content-Type: application/json" \
  -d '{
    "token": "reset-token-from-email",
    "new_password": "NewSecurePassword123!"
  }'

Response 200 OK​

{
  "message": "Password reset successful"
}

Change password​

Change the password for the currently authenticated user.

POST /api/v1/auth/change-password

Requires: Bearer token

Request body​

FieldTypeRequiredDescription
current_passwordstringYesCurrent password
new_passwordstringYesNew password (min 8 characters)

Example​

curl -X POST https://your-tms-instance.com/api/v1/auth/change-password \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "current_password": "OldPassword123!",
    "new_password": "NewPassword123!"
  }'

Response 200 OK​

{
  "message": "Password changed successfully"
}

OAuth login​

ProvaLab.io supports single sign-on through Google and GitHub.

Start Google OAuth​

GET /api/v1/auth/google

Returns an authorization URL to redirect the user to Google's consent screen:

{
  "authorization_url": "https://accounts.google.com/o/oauth2/v2/auth?..."
}

Start GitHub OAuth​

GET /api/v1/auth/github

Returns an authorization URL to redirect the user to GitHub's consent screen:

{
  "authorization_url": "https://github.com/login/oauth/authorize?..."
}

After the user authorizes the application, they are redirected back to ProvaLab.io with an access token. OAuth callbacks are handled automatically by the platform.

API keys​

API keys provide long-lived authentication for scripts, CI/CD pipelines, and integrations. Manage API keys from Settings > Security > API Keys in the ProvaLab.io web UI.

Once created, include the key in every request:

curl https://your-tms-instance.com/api/v1/organizations/1/projects \
  -H "X-API-Key: sk_live_abc123..."

API keys inherit the permissions of the user who created them. You can scope keys to specific operations when creating them in the Settings UI.

Next steps​