Skip to main content

​
Authentication

The Artos API uses Bearer token authentication. All endpoints require a valid Bearer token to be included in the Authorization header, except for /api/v1/search/status which is publicly accessible.

​
Bearer Token Authentication

​
Getting a Token

Obtain a Bearer token from your organization administrator. The token grants access scoped to your organization and enables all authenticated operations.

​
Using Bearer Tokens

Include the token in the Authorization header as a Bearer token for all requests: 
Authorization: Bearer YOUR_TOKEN_HERE

​
Example API Request

curl -X GET "https://api.artosai.com/api/v1/templates/" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json"

​
Python Example

import requests

headers = {
    "Authorization": "Bearer YOUR_TOKEN_HERE",
    "Content-Type": "application/json"
}

# List templates
response = requests.get(
    "https://api.artosai.com/api/v1/templates/",
    headers=headers
)

templates = response.json()
print(templates)

​
JavaScript Example

const token = "YOUR_TOKEN_HERE";

fetch("https://api.artosai.com/api/v1/templates/", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${token}`,
    "Content-Type": "application/json"
  }
})
  .then(response => response.json())
  .then(data => console.log(data));

​
Token Format and Claims

Bearer tokens are JWT tokens containing organization and user context. The token automatically provides:
  • Organization ID: Scopes all resource access to your organization
  • User ID: Identifies the authenticated user for audit trails
  • Permissions: Controls which operations are available
  • Expiration: Token validity period

​
Organization Scoping

All resources are automatically scoped to your organization. A user’s token contains their organization context, ensuring:
  • Users can only access their organization’s resources
  • Resources are automatically filtered by organization
  • Cross-organization access is prevented
  • Multi-tenant isolation is enforced

​
Example

When you make a request: 
GET /api/v1/documents/
The API returns only documents belonging to your organization, based on your Bearer token. No explicit organization filtering is needed.

​
Error Responses

​
Missing Authorization Header (401 Unauthorized)

{
  "detail": "Not authenticated"
}
Solution: Include your Bearer token in the Authorization header: 
-H "Authorization: Bearer YOUR_TOKEN_HERE"

​
Invalid Token (401 Unauthorized)

{
  "detail": "Invalid authentication credentials"
}
Possible Causes:
  • Token is malformed
  • Token has expired
  • Token was issued for a different organization
  • Token has been revoked
Solution: Obtain a fresh token from your organization administrator.

​
Wrong Organization (403 Forbidden)

{
  "detail": "User has no organization or not authorized"
}
Possible Causes:
  • Token is for a different organization
  • User account is not properly configured
Solution: Contact your organization administrator to verify your account setup.

​
Public Endpoints (No Auth Required)

The /api/v1/search/status endpoint is publicly accessible and does not require authentication: 
# No Authorization header needed
curl -X GET "https://api.artosai.com/api/v1/search/status"

​
Security Best Practices

​
Token Storage

  • Never commit tokens to version control systems
  • Use environment variables for token management
  • Store securely in your application’s secret management system
  • Don’t log tokens in debug output or error messages

​
Token Usage

# Good: Use environment variable
export ARTOS_TOKEN="your_token_here"
curl -X GET "https://api.artosai.com/api/v1/templates/" \
  -H "Authorization: Bearer $ARTOS_TOKEN"

# Bad: Hardcoded token in code
curl -X GET "https://api.artosai.com/api/v1/templates/" \
  -H "Authorization: Bearer abc123xyz"

​
Token Rotation

  • Request a new token periodically from your organization administrator
  • Rotate tokens in case of suspected compromise
  • Revoke tokens when team members leave

​
HTTPS Only

Always use HTTPS when making API requests with Bearer tokens: 
# Good: HTTPS
curl -X GET "https://api.artosai.com/api/v1/templates/" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Bad: HTTP (insecure)
curl -X GET "http://api.artosai.com/api/v1/templates/" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Common Issues

​
”Not authenticated” Error

The most common cause is a missing or malformed Authorization header. Check:
  1. Is the Authorization header present?
  2. Does it use the correct format: Authorization: Bearer TOKEN?
  3. Is the token valid and not expired?
  4. Is the token for your organization?

​
”Invalid authentication credentials” Error

The token provided is not valid. Solutions:
  1. Verify the token value is correct (no extra spaces or characters)
  2. Obtain a fresh token from your administrator
  3. Check that the token hasn’t been revoked
  4. Ensure the token is for the correct environment (production vs. staging)

​
Token Handling in Different Languages

​
Python with Requests

import os
import requests

token = os.environ.get("ARTOS_TOKEN")
headers = {"Authorization": f"Bearer {token}"}

response = requests.get(
    "https://api.artosai.com/api/v1/documents/",
    headers=headers
)

​
Node.js with Fetch

const token = process.env.ARTOS_TOKEN;

const response = await fetch(
  "https://api.artosai.com/api/v1/documents/",
  {
    headers: { "Authorization": `Bearer ${token}` }
  }
);

​
Go

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	token := os.Getenv("ARTOS_TOKEN")

	req, _ := http.NewRequest("GET", "https://api.artosai.com/api/v1/documents/", nil)
	req.Header.Add("Authorization", fmt.Sprintf("Bearer %s", token))

	client := &http.Client{}
	resp, _ := client.Do(req)
	defer resp.Body.Close()

	body, _ := io.ReadAll(resp.Body)
	fmt.Println(string(body))
}

​
Support

If you have issues with authentication:
  1. Contact your organization administrator to verify your token is valid
  2. Check the endpoint documentation to confirm the endpoint requires authentication
  3. Review error responses for specific details about what went wrong
  4. Verify HTTPS is being used for all requests with authentication