Skip to main content

Authentication

The Heimdall API uses Bearer token authentication for secure access to protected endpoints.

Authentication Methods​

Bearer Token Authentication​

All authenticated requests must include an Authorization header with a Bearer token:

Authorization: Bearer YOUR_API_TOKEN

Obtaining an API Token​

API tokens are issued by system administrators. Contact your admin to request a token.

Token Roles​

There are two role types:

RoleAccess LevelDescription
VIEWERRead-onlyCan view GPS data and public endpoints
ADMINFull accessCan create, update, delete all resources

Making Authenticated Requests​

Using cURL​

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://api.elcto.com/v1/gps/current

Using JavaScript (Fetch)​

const response = await fetch('https://api.elcto.com/v1/gps/current', {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
});

const data = await response.json();

Using Python (Requests)​

import requests

headers = {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.elcto.com/v1/gps/current',
    headers=headers
)

data = response.json()

Validate Your Token​

You can validate your token using the validation endpoint:

POST /v1/auth/validate
Content-Type: application/json

{
  "token": "YOUR_TOKEN"
}

Response:

{
  "valid": true,
  "token": {
    "id": "abc-123",
    "description": "My API Token",
    "role": "ADMIN",
    "createdAt": "2025-01-01T00:00:00Z"
  }
}

GraphQL Authentication​

The GraphQL endpoint (/v1/gql) requires authentication for all queries and mutations. Include the Authorization header with your Bearer token:

curl -X POST https://api.elcto.com/v1/gql \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ me { tokenId description role isAdmin } }"}'

Response:

{
  "data": {
    "me": {
      "tokenId": "abc-123",
      "description": "My API Token",
      "role": "ADMIN",
      "isAdmin": true
    }
  }
}

Using GraphiQL (Development Only)​

The GraphiQL IDE (/v1/graphiql) is only available in development environments. To use it:

  1. Ensure APP_ENV is not set to production
  2. Open http://localhost:3000/v1/graphiql
  3. Click "HTTP HEADERS" at the bottom left
  4. Add your authorization header:
{
  "Authorization": "Bearer YOUR_TOKEN"
}
  1. Execute your queries
warning

GraphiQL is disabled in production environments for security. Use the /v1/gql endpoint directly with your HTTP client in production.

WebSocket Authentication​

WebSocket connections do not require authentication at the connection level. Subscribe to channels after connecting:

const ws = new WebSocket('wss://api.elcto.com/v1/ws');

ws.onopen = () => {
  // Subscribe to GPS updates
  ws.send(JSON.stringify({
    type: 'Subscribe',
    channel: 'gps'
  }));
};

Authentication Errors​

401 Unauthorized​

Returned when no authentication token is provided or the token is invalid:

{
  "error": "Unauthorized",
  "message": "Invalid or missing authentication token"
}

403 Forbidden​

Returned when the authenticated user lacks sufficient permissions:

{
  "error": "Forbidden",
  "message": "Insufficient permissions for this operation"
}

Security Best Practices​

Security Tips
  1. Never expose your API token in client-side code or public repositories
  2. Use HTTPS in production to encrypt token transmission
  3. Rotate tokens regularly for enhanced security
  4. Use environment variables to store tokens
  5. Implement token expiration policies in your applications

Rate Limiting​

Authenticated requests are subject to rate limiting:

  • Default: 100 requests per minute per token
  • Admin endpoints: 30 requests per 60 seconds

Rate limit information is included in response headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640000000

Next Steps​