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

Field	Type	Required	Description
username	string	Yes	Your email address
password	string	Yes	Your password

Example

curl -X POST https://tms.provalab.io/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

Field	Type	Required	Description
email	string	Yes	Email address
username	string	Yes	Unique username
password	string	Yes	Password (min 8 characters)
full_name	string	Yes	Full name

Example

curl -X POST https://tms.provalab.io/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

Field	Type	Required	Description
refresh_token	string	Yes	The refresh token from login

Example

curl -X POST https://tms.provalab.io/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://tms.provalab.io/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

Field	Type	Required	Description
email	string	Yes	The account email address

Example

curl -X POST https://tms.provalab.io/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

Field	Type	Required	Description
token	string	Yes	Reset token from the email link
new_password	string	Yes	New password (min 8 characters)

Example

curl -X POST https://tms.provalab.io/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

Field	Type	Required	Description
current_password	string	Yes	Current password
new_password	string	Yes	New password (min 8 characters)

Example

curl -X POST https://tms.provalab.io/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

TMS 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 TMS 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 TMS web UI.

Once created, include the key in every request:

curl https://tms.provalab.io/api/v1/organizations/1/projects \
  -H "X-API-Key: tms_..."

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

• Test Management API -- Projects, test cases, runs, and results
• AI API -- Test generation and failure analysis