API-toegang

Een verzoek authenticeren

Gebruik https://allocyn.com/api/public/v1 voor de gehoste service. Gebruik voor een andere installatie het HTTPS-domein en het eventuele basispad, zoals https://example.com/allocyn/api/public/v1.

Stuur de volledige sleutel mee in X-Allocyn-Key. Een Bearer-token, geheime webhooksleutel of aanmeldcookie van de browser is geen vervanging. Stel ALLOCYN_API_KEY veilig in voordat u het PowerShell-voorbeeld uitvoert; dit doet één leesverzoek.

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

Ondersteunde resources en scopes

Deze routes zijn relatief aan de basis-URL van de openbare API en accepteren GET. Er zijn geen openbare eindpunten voor het wijzigen van deze resources, tijdregistratie, het genereren of downloaden van rapporten, of het beheren van clients en webhooks met een API-sleutel.

Paginering

Elke resource retourneert data en meta. Verhoog page zolang meta.hasMore true is. De waarde returned telt alleen deze pagina; een pagina voorbij de beschikbare gegevens heeft een lege data-array.

Projecten worden oplopend op code gesorteerd, werkitems op titel en personen op weergavenaam; rapporten worden aflopend op generatietijd gesorteerd. Paginering is geen momentopname: wijzigingen en gelijke sorteerwaarden kunnen paginagrenzen verschuiven. Verwijder duplicaten op basis van id en stem de gegevens periodiek af. Filteren, aangepaste sortering en modified-since-parameters worden niet ondersteund.

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

Referentie voor responsvelden

Deze velden staan in elk data-object. Identificatoren zijn ondoorzichtige tekenreeksen, status- en health-waarden zijn enumnamen van de server, datumwaarden gebruiken YYYY-MM-DD en UTC-tijdstempels gebruiken ISO 8601. Optionele velden kunnen null zijn. Identificatoren van gerelateerde records zijn geen download-URL’s.

Limieten en fouten

De clientlimiet geldt gezamenlijk voor de openbare API-verzoeken van die client in vaste UTC-minuutvensters. Een aparte algemene limiet staat 300 verzoeken per minuut per extern IP-adres toe, gedeeld met andere verzoeken vanaf dat IP-adres. Een hogere clientinstelling omzeilt die limiet niet; de hostinginfrastructuur kan extra limieten opleggen.

Een overschrijding van de clientlimiet retourneert 401 zonder specifieke reden of resetheader. Controleer de aanmeldgegevens en scopes en probeer een verzoek dat op de clientlimiet vastliep opnieuw na het begin van de volgende UTC-minuut. Blijf niet proberen bij aanhoudende 401-responsen. Foutteksten kunnen vertaald zijn en proxy’s kunnen andere responsinhoud retourneren.

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

Organisatiescope en beschikbaarheid

Een API-sleutel behoort tot één organisatie. Binnen de geselecteerde scopes leest de sleutel organisatiebrede gegevens, niet alleen de projecttoewijzingen van de maker. Er is geen header of queryparameter waarmee de aanroeper een organisatie kan kiezen. Geef de sleutel alleen aan services die deze informatie mogen ontvangen.

Aanroepen vereisen een actieve organisatie, een ingeschakelde module Integraties, een geschikt abonnement en ingeschakelde API-rechten. Een niet-verlopen proefperiode of geldige betaalde periode kan toegang geven; een beëindigde proefperiode of herstelperiode van een abonnement niet. Het maken van clients is ook onderworpen aan de ingestelde API-clientlimiet.

Een sleutel vervangen of intrekken

Bij bestaande clients kunt u de sleutel niet opnieuw tonen of roteren en de scopes of vervaldatum niet wijzigen. Houd rekening met de limiet voor actieve clients wanneer oude en nieuwe clients tegelijk bestaan. Stem een onderbreking af of neem contact op met uw beheerder als er geen ruimte beschikbaar is.

• Maak een vervanger met een andere naam en de vereiste scopes, verzoeklimiet en vervaldatum; sla de nieuw getoonde sleutel op.
• Werk uw service bij en controleer of een toegestaan leesverzoek slaagt. Trek daarna de oude client in via API-toegang.
• Trek bij een vermoedelijk gecompromitteerde sleutel eerst de client in. Intrekking stopt toekomstige authenticatie, maar kan al gelezen gegevens niet terughalen of een al toegestaan verzoek annuleren. Ingetrokken clients blijven in de lijst staan en kunnen niet via deze interface opnieuw worden geactiveerd.

Referentie voor API-clientbeheer

Deze routes gebruiken normale geauthenticeerde organisatietoegang, niet X-Allocyn-Key. Plaats /api/organization/integration-operations en het eventuele basispad van de installatie ervoor. Voor bekijken is integrations.view vereist; voor maken en intrekken ook integrations.manage.

Een clientsamenvatting bevat id, name, requestsPerMinute, expiresAtUtc, isActive, keyPrefix, lastUsedAtUtc, permissions en version. Stuur bij intrekking de nieuwste niet-interpreteerbare Base64-versie mee; laad opnieuw na een 409-conflict. Validatiefouten retourneren 400 en authenticatie- of autorisatiefouten kunnen 401 of 403 retourneren.

Vervaldatum en probleemoplossing

Geef in beheerverzoeken voor expiresAtUtc een toekomstig UTC-tijdstip op, zoals 2027-01-01T00:00:00Z, of null. Het vervaldatumveld van het portaal zet de lokale datum en tijd niet expliciet om naar UTC vóór verzending. Controleer de opgeslagen vervaldatum en ga niet uit van tijdzoneconversie. Verlopen maar niet ingetrokken clients tellen nog mee voor de limiet van actieve clients.

Als de pagina of de knop voor het maken ontbreekt, controleer dan de geselecteerde organisatie, integrations.view, integrations.manage, abonnementstoegang en limieten. Geef ondersteuning de route, het UTC-tijdstip, de status en indien beschikbaar de responsheader X-Correlation-ID. Stuur nooit uw API-sleutel.