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

# Authentication

> Authenticate with the Manifest API

The Manifest API supports multiple authentication methods to accommodate different integration scenarios.

## Authentication methods

### JWT token authentication

The primary authentication method uses JSON Web Tokens (JWT).

#### Sign in

```http theme={null}
POST /api/client/auth/sign-in
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "your-password"
}
```

Response:

```json theme={null}
{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "refresh-token-here",
    "user": {
      "id": 123,
      "email": "user@example.com",
      "firstName": "John",
      "lastName": "Doe"
    }
  }
}
```

#### Using the token

Include the JWT token in the Authorization header:

```http theme={null}
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```

#### Token refresh

Tokens expire after a set period. Use the refresh token to obtain a new access token:

```http theme={null}
POST /api/client/auth/refresh
Content-Type: application/json

{
  "refreshToken": "refresh-token-here"
}
```

### Cookie-based authentication

For web applications, cookie-based authentication is available:

```http theme={null}
POST /api/client/auth/sign-in
Content-Type: application/json
Cookie: session=session-cookie-value

{
  "email": "user@example.com",
  "password": "your-password"
}
```

The server sets a session cookie that is automatically included in subsequent requests.

### OAuth and SSO

#### OpenID Connect (OIDC)

```http theme={null}
GET /api/client/auth/oidc?provider=provider-name
```

This redirects to the OIDC provider for authentication.

#### Okta SAML

```http theme={null}
POST /api/client/auth/okta-saml
Content-Type: application/json

{
  "samlResponse": "base64-encoded-saml-response"
}
```

#### Microsoft Dynamics

```http theme={null}
GET /api/client/auth/ms-dynamics
```

Redirects to Microsoft authentication.

### Power Apps authentication

For Power Apps integrations, use Entra ID (Azure AD) authentication:

```http theme={null}
Authorization: Bearer entra-id-token
```

The API validates the token with Microsoft Graph API.

## GraphQL authentication

For GraphQL requests, include the token in the Authorization header:

```http theme={null}
POST /api/client/graphql
Authorization: Bearer your-jwt-token
Content-Type: application/json

{
  "query": "query { users { id email } }"
}
```

## Admin authentication

Admin endpoints require admin-level authentication:

```http theme={null}
POST /api/admin/auth/sign-in
Content-Type: application/json

{
  "username": "admin",
  "password": "admin-password"
}
```

## Token expiration

* **Access tokens**: Expire after 24 hours
* **Refresh tokens**: Expire after 30 days
* **Session cookies**: Expire after 7 days of inactivity

## Security best practices

### Store tokens securely

* Never store tokens in localStorage for production applications
* Use httpOnly cookies when possible
* Store tokens in secure, encrypted storage

### Token rotation

Implement token rotation to minimize security risks:

```javascript theme={null}
async function refreshAccessToken(refreshToken) {
  const response = await fetch('/api/client/auth/refresh', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ refreshToken })
  });
  
  const data = await response.json();
  return data.token;
}
```

### Handle token expiration

Implement automatic token refresh:

```javascript theme={null}
async function apiRequest(url, options = {}) {
  let response = await fetch(url, {
    ...options,
    headers: {
      ...options.headers,
      'Authorization': `Bearer ${accessToken}`
    }
  });
  
  if (response.status === 401) {
    // Token expired, refresh it
    accessToken = await refreshAccessToken(refreshToken);
    
    // Retry request with new token
    response = await fetch(url, {
      ...options,
      headers: {
        ...options.headers,
        'Authorization': `Bearer ${accessToken}`
      }
    });
  }
  
  return response;
}
```

### Logout

Always implement proper logout:

```http theme={null}
POST /api/client/auth/sign-out
Authorization: Bearer your-jwt-token
```

This invalidates the token on the server.

## Permissions and roles

Users have different permission levels based on their roles:

* **Admin** - Full system access
* **User Admin** - User management within organization
* **Author** - Create and edit templates
* **Operator** - Execute jobs and record data
* **Approver** - Approve template versions
* **Publisher** - Publish templates
* **Viewer** - Read-only access

Check user permissions before making API calls that require specific roles.

## Multi-tenancy

The API supports multi-tenant architecture. Each request is scoped to the authenticated user's client:

```http theme={null}
Authorization: Bearer your-jwt-token
X-Client-ID: client-identifier
```

The client ID is automatically determined from the authentication token.

## On-premise deployments

For on-premise deployments, license key validation is required:

```http theme={null}
POST /api/admin/license-on-prem
Content-Type: application/json

{
  "licenseKey": "your-license-key"
}
```

## Error responses

### Invalid credentials

```json theme={null}
{
  "success": false,
  "error": {
    "message": "Invalid email or password",
    "code": "INVALID_CREDENTIALS"
  }
}
```

### Expired token

```json theme={null}
{
  "success": false,
  "error": {
    "message": "Token has expired",
    "code": "TOKEN_EXPIRED"
  }
}
```

### Insufficient permissions

```json theme={null}
{
  "success": false,
  "error": {
    "message": "Insufficient permissions",
    "code": "FORBIDDEN"
  }
}
```

## Next steps

* [GraphQL API](/api-reference/graphql/overview) - GraphQL endpoint documentation
* [REST API](/api-reference/rest/overview) - REST endpoint documentation