> ## Documentation Index
> Fetch the complete documentation index at: https://docs.artosai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Artos API uses Bearer token authentication. All endpoints (except /search/status) require a valid Bearer token in the Authorization header.

# 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 by calling the `/get-access-token` endpoint with your `user_id`. The token is valid for a fixed period and grants access scoped to your organization.

**Endpoint**: `POST /get-access-token`

**Request body**:

```json theme={null}
{
  "user_id": "YOUR_USER_ID"
}
```

**Response**:

```json theme={null}
{
  "access_token": "YOUR_ACCESS_TOKEN"
}
```

**Example**:

```bash theme={null}
curl -X POST "https://api.artosai.com/get-access-token" \
  -H "Content-Type: application/json" \
  -d '{"user_id": "YOUR_USER_ID"}'
```

```python theme={null}
import requests

response = requests.post(
    "https://api.artosai.com/get-access-token",
    json={"user_id": "YOUR_USER_ID"}
)

access_token = response.json()["access_token"]
```

The token expires after a fixed period. Request a new token by calling this endpoint again with your `user_id`.

### Using Bearer Tokens

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

```bash theme={null}
Authorization: Bearer YOUR_TOKEN_HERE
```

### Example API Request

```bash theme={null}
curl -X GET "https://api.artosai.com/api/v1/templates/" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json"
```

### Python Example

```python theme={null}
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

```javascript theme={null}
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:

```bash theme={null}
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)

```json theme={null}
{
  "detail": "Not authenticated"
}
```

**Solution**: Include your Bearer token in the Authorization header:

```bash theme={null}
-H "Authorization: Bearer YOUR_TOKEN_HERE"
```

### Invalid Token (401 Unauthorized)

```json theme={null}
{
  "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)

```json theme={null}
{
  "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:

```bash theme={null}
# 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

```bash theme={null}
# 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:

```bash theme={null}
# 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

```python theme={null}
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

```javascript theme={null}
const token = process.env.ARTOS_TOKEN;

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

#### Go

```go theme={null}
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