API access

Authenticate a request

Use https://allocyn.com/api/public/v1 for the hosted service. For another deployment, use its HTTPS domain and any base path, such as https://example.com/allocyn/api/public/v1.

Send the complete key in X-Allocyn-Key. A Bearer token, webhook secret, or browser login cookie is not a substitute. Provision ALLOCYN_API_KEY securely before running the PowerShell example; it makes one read request.

GET /api/public/v1/projects?page=1&pageSize=100 HTTP/1.1
Host: allocyn.com
Accept: application/json
X-Allocyn-Key: <your-api-key>

$apiBase = 'https://allocyn.com/api/public/v1'
if ([string]::IsNullOrWhiteSpace($env:ALLOCYN_API_KEY)) {
    throw 'Set ALLOCYN_API_KEY securely before running this example.'
}
$apiHeaders = @{ 'X-Allocyn-Key' = $env:ALLOCYN_API_KEY; Accept = 'application/json' }
$page = Invoke-RestMethod -Method Get -Uri "$apiBase/projects?page=1&pageSize=100" -Headers $apiHeaders
$page.data | Select-Object code, name, status, health

Supported resources and scopes

These routes are relative to the public API base URL and accept GET. There are no public endpoints for changing these resources, logging time, generating or downloading reports, or managing clients and webhooks with an API key.

Pagination

Every resource returns data and meta. Increase page while meta.hasMore is true. The returned value counts this page only; a page beyond the available data has an empty data array.

Projects sort by code, work items by title, and people by display name, all ascending; reports sort by generation time descending. Paging is not a snapshot: changes and equal sort values can shift page boundaries. Deduplicate by id and reconcile periodically. No filtering, custom sorting, or modified-since parameters are supported.

{
  "data": [{
    "id": "11111111-1111-7111-8111-111111111111",
    "code": "CLIENT-PORTAL",
    "name": "Client portal",
    "status": "Active",
    "health": "OnTrack",
    "startsOn": "2026-09-01",
    "currentTargetEndDate": "2026-11-30"
  }],
  "meta": { "page": 1, "pageSize": 100, "returned": 1, "hasMore": false }
}

Response field reference

These fields appear in each data object. Identifiers are opaque strings, status and health values are server enum names, date-only values use YYYY-MM-DD, and UTC timestamps use ISO 8601. Optional fields can be null. Related-record identifiers are not download URLs.

Limits and errors

The client limit is shared across its public API requests in fixed UTC-minute windows. A separate global limit allows 300 requests per minute per remote IP, shared with other requests from that IP. A higher client setting does not bypass that limit; hosting infrastructure can impose additional limits.

Client-level rate limiting returns 401 without a dedicated reason or reset header. After checking credentials and scopes, retry a client-limit failure after the next UTC-minute boundary. Do not repeatedly retry persistent 401 responses. Error wording may be localized, and proxies can return different bodies.

{
  "status": 401,
  "title": "API access denied",
  "detail": "The API key is invalid, expired, revoked, outside its rate limit, or missing the required scope."
}

Organization scope and availability

An API key belongs to one organization. Within its selected scopes it reads organization-wide data, not just its creator’s project assignments. There is no caller-selected organization header or query parameter. Give the key only to services authorized to receive that information.

Calls require an active organization, its Integrations module enabled, an eligible subscription, and an enabled API entitlement. An unexpired trial or qualifying paid period can permit access; an ended trial or subscription’s recovery period does not. Creation is also subject to the configured API client limit.

Replace or revoke a key

Existing clients have no in-place key reveal, rotation, scope edit, or expiry edit. Allow for your active-client limit when overlapping old and new clients. If no slot is available, coordinate an interruption or contact your administrator.

• Create a replacement with a distinct name and the required scopes, rate limit, and expiry; store its newly revealed key.
• Update your service and confirm an authorized read succeeds, then revoke the old client from API access.
• For suspected compromise, revoke first. Revocation stops future authentication but cannot withdraw data already read or cancel a request already authorized. Revoked clients remain listed and cannot be reactivated through this interface.

API client management reference

These routes use normal authenticated organization access, not X-Allocyn-Key. Prefix them with /api/organization/integration-operations and any deployment base path. Viewing requires integrations.view; creation and revocation also require integrations.manage.

A client summary contains id, name, requestsPerMinute, expiresAtUtc, isActive, keyPrefix, lastUsedAtUtc, permissions, and version. Send the latest opaque Base64 version when revoking; reload after a 409 conflict. Validation errors return 400, and authentication or authorization failures can return 401 or 403.

Expiry and troubleshooting

In management requests, supply a future UTC timestamp such as 2027-01-01T00:00:00Z, or null, for expiresAtUtc. The portal’s expiry control does not explicitly convert its local date/time to UTC before submission. Verify the stored expiry rather than assuming time-zone conversion. Expired but unrevoked clients still count toward the active-client limit.

If the page or creation button is missing, check organization selection, integrations.view, integrations.manage, subscription access, and limits. For support, provide the route, UTC time, status, and X-Correlation-ID response header when available. Never send your API key.