Authentication

Planned feature: The authentication flow described here represents the intended JWT authentication design. This is not yet implemented in the current codebase.

Overview

The planned OrgStack API will use JSON Web Tokens (JWT) for authentication. To access protected endpoints, you will need to include a valid JWT token in the Authorization header of your requests.

JWT tokens have an expiration time. When your token expires, you’ll need to obtain a new one by logging in again.

Authentication flow

Follow these steps to authenticate and make authorized API requests:

Obtain credentials

Ensure you have valid user credentials (username/email and password) for the OrgStack system.

Request a token

Send a POST request to the /api/auth/login endpoint with your credentials.

Store the token

Save the JWT token returned in the response securely in your application.

Use the token

Include the token in the Authorization header as a Bearer token for all subsequent requests.

Obtaining a JWT token

To obtain a JWT token, send a POST request to the login endpoint with your credentials.

Endpoint

POST /api/auth/login

Request body

Field	Type	Required	Description
`username`	string	Yes	Your username or email address
`password`	string	Yes	Your account password

Example request

curl -X POST http://localhost:8080/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "[email protected]",
    "password": "securepassword"
  }'

Success response

Status Code: 200 OK

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
  "userId": "123e4567-e89b-12d3-a456-426614174000",
  "username": "[email protected]",
  "expiresIn": 86400
}

Field	Type	Description
`token`	string	The JWT token to use for authentication
`userId`	string	The unique identifier of the authenticated user
`username`	string	The username of the authenticated user
`expiresIn`	integer	Token expiration time in seconds

Error responses

Status Code: 401 Unauthorized

{
  "error": "Unauthorized",
  "message": "Invalid username or password",
  "timestamp": "2026-03-01T10:30:00Z"
}

Status Code: 400 Bad Request

{
  "error": "Bad Request",
  "message": "Username and password are required",
  "timestamp": "2026-03-01T10:30:00Z"
}

Never share your JWT token or include it in client-side code that could be publicly accessible. Treat tokens like passwords.

Using JWT tokens

Once you have a JWT token, include it in the Authorization header of your requests using the Bearer authentication scheme.

Header format

Authorization: Bearer YOUR_JWT_TOKEN

Example authenticated request

curl -X GET http://localhost:8080/api/organizations \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Token expiration

JWT tokens expire after a set period (typically 24 hours). When your token expires, API requests will return a 401 Unauthorized response.

Handling expired tokens

When you receive a 401 error due to an expired token:

Request a new token by calling /api/auth/login again
Update your stored token with the new one
Retry the failed request with the new token

Implement automatic token refresh logic in your application to handle expiration gracefully without requiring user intervention.

Security best practices

Follow these security best practices when working with JWT tokens:

Use HTTPS in production

Always use HTTPS to encrypt tokens in transit. The localhost URL shown in examples is for development only.

Store tokens securely

Store tokens in secure storage mechanisms appropriate for your platform (e.g., encrypted storage, secure cookies, environment variables).

Don't expose tokens

Never log tokens, commit them to version control, or expose them in client-side code.

Implement token refresh

Build automatic token refresh logic to handle expiration without user disruption.

Handle logout

Clear stored tokens when users log out to prevent unauthorized access.

Common authentication errors

Status Code	Error	Solution
`401`	Invalid username or password	Verify your credentials are correct
`401`	Invalid or expired token	Request a new token by logging in again
`401`	Missing authorization header	Include the `Authorization` header with your token
`403`	Insufficient permissions	Your account lacks permission for this operation

If you receive multiple 401 errors with valid credentials, your account may be locked or disabled. Contact your administrator.

Next steps

Now that you understand authentication, you can:

Explore available API endpoints in the documentation
Build your integration using authenticated requests
Implement error handling for authentication failures

Overview

Endpoints

Overview

Authentication flow

Obtaining a JWT token

Endpoint

Request body

Example request

Success response

Error responses

Using JWT tokens

Header format

Example authenticated request

Token expiration

Handling expired tokens

Security best practices

Common authentication errors

Next steps

Build docs developers (and LLMs) love

Overview

Endpoints

​Overview

​Authentication flow

​Obtaining a JWT token

​Endpoint

​Request body

​Example request

​Success response

​Error responses

​Using JWT tokens

​Header format

​Example authenticated request

​Token expiration

​Handling expired tokens

​Security best practices

​Common authentication errors

​Next steps

Build docs developers (and LLMs) love

Overview

Authentication flow

Obtaining a JWT token

Endpoint

Request body

Example request

Success response

Error responses

Using JWT tokens

Header format

Example authenticated request

Token expiration

Handling expired tokens

Security best practices

Common authentication errors

Next steps