API Authentication

All API requests must include a valid authentication token.

Bearer Token

Include your access token in the Authorization header:

curl -X GET https://api.holyplatform.com/v1/people \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json"

Church Context

If your account has access to multiple churches, include the church ID header:

curl -X GET https://api.holyplatform.com/v1/people \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Church-ID: YOUR_CHURCH_ID" \
  -H "Content-Type: application/json"

If omitted, the API uses the church associated with your account.

Obtaining a Token

curl -X POST https://api.holyplatform.com/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@yourchurch.com",
    "password": "your_password"
  }'

Response:

{
  "data": {
    "access_token": "your_access_token",
    "refresh_token": "your_refresh_token",
    "expires_in": 3600,
    "token_type": "Bearer"
  }
}

Refreshing a Token

Access tokens expire after a period of time. Use the refresh token to obtain a new access token:

curl -X POST https://api.holyplatform.com/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "your_refresh_token"
  }'

Error Responses

401 Unauthorized

Returned when the token is missing, expired, or invalid:

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or expired access token",
    "status": 401
  }
}

403 Forbidden

Returned when the token is valid but the user lacks permission:

{
  "error": {
    "code": "forbidden",
    "message": "You do not have permission to access this resource",
    "status": 403
  }
}

On this page