Authentication - Taqtile Documentation

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).

POST /api/client/auth/sign-in
Content-Type: application/json

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

Response:

{
  "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:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Token refresh

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

POST /api/client/auth/refresh
Content-Type: application/json

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

For web applications, cookie-based authentication is available:

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)

GET /api/client/auth/oidc?provider=provider-name

This redirects to the OIDC provider for authentication.

Okta SAML

POST /api/client/auth/okta-saml
Content-Type: application/json

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

Microsoft Dynamics

GET /api/client/auth/ms-dynamics

Redirects to Microsoft authentication.

Power Apps authentication

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

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:

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:

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:

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:

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:

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:

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:

POST /api/admin/license-on-prem
Content-Type: application/json

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

Error responses

Invalid credentials

{
  "success": false,
  "error": {
    "message": "Invalid email or password",
    "code": "INVALID_CREDENTIALS"
  }
}

Expired token

{
  "success": false,
  "error": {
    "message": "Token has expired",
    "code": "TOKEN_EXPIRED"
  }
}

Insufficient permissions

{
  "success": false,
  "error": {
    "message": "Insufficient permissions",
    "code": "FORBIDDEN"
  }
}

Next steps

GraphQL API - GraphQL endpoint documentation
REST API - REST endpoint documentation

​Authentication methods

​JWT token authentication

​Sign in

​Using the token

​Token refresh

​Cookie-based authentication

​OAuth and SSO

​OpenID Connect (OIDC)

​Okta SAML

​Microsoft Dynamics

​Power Apps authentication

​GraphQL authentication

​Admin authentication

​Token expiration

​Security best practices

​Store tokens securely

​Token rotation

​Handle token expiration

​Logout

​Permissions and roles

​Multi-tenancy

​On-premise deployments

​Error responses

​Invalid credentials

​Expired token

​Insufficient permissions

​Next steps