Authentication API Reference

This document details the endpoints available for authenticating users and managing API access.

Authentication Overview

Our API uses a token-based authentication system. Upon successful login, a JSON Web Token (JWT) is issued, which must be included in subsequent requests to protected endpoints. The token should be passed in the Authorization header as a Bearer token.

Example: Authorization: Bearer YOUR_JWT_TOKEN

Login Endpoint

Authenticates a user and returns an access token.

POST /api/v1/auth/login

Request Body:

Field Type Required Description
username String Yes The user's unique username.
password String Yes The user's password.

Success Response (200 OK):


{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 3600,
  "user": {
    "id": "user_123",
    "username": "jane.doe",
    "email": "jane.doe@example.com"
  }
}

Error Response (401 Unauthorized):


{
  "error": "Invalid credentials"
}
            

{
  "error": "User not found"
}

Refresh Token Endpoint

Obtains a new access token using a valid refresh token.

POST /api/v1/auth/refresh

Request Body:

Field Type Required Description
refreshToken String Yes The user's refresh token.

Success Response (200 OK):


{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 3600
}

Error Response (401 Unauthorized):


{
  "error": "Invalid or expired refresh token"
}

Logout Endpoint

Invalidates the user's current session and associated tokens.

POST /api/v1/auth/logout

Requires authentication. The Authorization: Bearer YOUR_JWT_TOKEN header must be present.

Success Response (200 OK):


{
  "message": "Successfully logged out"
}

Error Response (401 Unauthorized):


{
  "error": "Authentication required"
}

API Key Management (Optional)

For server-to-server integrations, you can generate and manage API keys. These keys provide programmatic access without user credentials.

POST /api/v1/auth/keys

Creates a new API key.

Requires authentication.

Success Response (201 Created):


{
  "keyId": "key_abc123",
  "apiKey": "sk_live_xxxxxxxxxxxxxxxxxxxxxxxx",
  "name": "My Integration Key",
  "createdAt": "2023-10-27T10:00:00Z"
}

GET /api/v1/auth/keys

Lists all API keys for the authenticated user/account.

Requires authentication.

Success Response (200 OK):


[
  {
    "keyId": "key_abc123",
    "name": "My Integration Key",
    "createdAt": "2023-10-27T10:00:00Z",
    "lastUsed": "2023-10-27T11:30:00Z"
  },
  {
    "keyId": "key_def456",
    "name": "Staging Key",
    "createdAt": "2023-10-25T09:00:00Z",
    "lastUsed": null
  }
]

DELETE /api/v1/auth/keys/{keyId}

Deletes an API key.

Requires authentication.

Replace {keyId} with the ID of the key to delete.

Success Response (204 No Content):

No response body.

Error Response (404 Not Found):


{
  "error": "API key not found"
}

Security Considerations

Back to top