Sanctum Authentication

Laravel Sanctum provides a lightweight authentication system for SPAs, mobile applications, and simple token-based APIs. GxP uses Sanctum for its API authentication.

Obtaining a Token

Via Dashboard

1. Log in to the GxP Dashboard
2. Navigate to Settings > API Tokens
3. Click Create New Token
4. Select the required scopes
5. Copy the generated token (it will only be shown once)

Via API (Personal Access Token)

If you have existing credentials, you can create tokens programmatically:

curl -X POST "https://api.gramercy.cloud/api/v1/auth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "your-password",
    "device_name": "My Application",
    "scopes": ["attendees:read", "attendees:write"]
  }'

Response:

{
  "token": "1|abc123...",
  "token_type": "Bearer",
  "expires_at": null
}

Using the Token

Include the token in the Authorization header for all API requests:

# Using curl
curl -X GET "https://api.gramercy.cloud/api/v1/projects" \
  -H "Authorization: Bearer 1|abc123..." \
  -H "Accept: application/json"

// Using fetch
const response = await fetch('https://api.gramercy.cloud/api/v1/projects', {
  headers: {
    'Authorization': 'Bearer 1|abc123...',
    'Accept': 'application/json'
  }
});

// Using Guzzle
$client = new \GuzzleHttp\Client();
$response = $client->get('https://api.gramercy.cloud/api/v1/projects', [
    'headers' => [
        'Authorization' => 'Bearer 1|abc123...',
        'Accept' => 'application/json'
    ]
]);

Token Abilities (Scopes)

When creating a token, you can specify abilities to limit what the token can access:

curl -X POST "https://api.gramercy.cloud/api/v1/auth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "your-password",
    "device_name": "Read-Only Client",
    "scopes": ["read"]
  }'

Available Scopes

Scope	Endpoints
*	All endpoints
read	All GET endpoints
attendees:read	GET /attendees/*
attendees:write	POST/PUT/DELETE /attendees/*
forms:read	GET /forms/*
forms:write	POST/PUT/DELETE /forms/*
access:read	GET /access-points/, /access-zones/
access:write	POST/PUT/DELETE access control endpoints

Revoking Tokens

Revoke Current Token

curl -X DELETE "https://api.gramercy.cloud/api/v1/auth/token" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Revoke All Tokens

curl -X DELETE "https://api.gramercy.cloud/api/v1/auth/tokens" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Token Expiration

By default, Sanctum tokens do not expire. However, your administrator may configure token expiration. Check your token's expiration:

curl -X GET "https://api.gramercy.cloud/api/v1/me" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Response:

{
  "data": {
    "id": 1,
    "name": "John Doe",
    "email": "john@example.com",
    "current_token": {
      "name": "My Application",
      "abilities": ["*"],
      "expires_at": null,
      "last_used_at": "2024-01-15T10:30:00Z"
    }
  }
}

SPA Authentication

For single-page applications hosted on the same domain, Sanctum supports cookie-based session authentication:

1. Initialize CSRF Protection:

// First, get the CSRF cookie
await fetch('https://api.gramercy.cloud/sanctum/csrf-cookie', {
  credentials: 'include'
});

2. Make Authenticated Requests:

// Include credentials in subsequent requests
const response = await fetch('https://api.gramercy.cloud/api/v1/projects', {
  credentials: 'include',
  headers: {
    'Accept': 'application/json'
  }
});

Troubleshooting

"Unauthenticated" Response

• Verify the token is correctly formatted: Bearer TOKEN
• Check that the token hasn't been revoked
• Ensure the token has the required abilities/scopes

"Token Mismatch" Error

• For SPA authentication, ensure you've fetched the CSRF cookie first
• Check that credentials are being sent with requests (credentials: 'include')

"Unable to authenticate" Error

• Verify the email and password are correct
• Check that the user account is active
• Ensure the device name is provided when creating tokens