# Overzicht REST API Wat de REST API van plnnrly is, waar hij draait, hoe je je authenticeert en hoe je een token krijgt. Met de REST API leest en wijzigt je eigen code je plnnrly-gegevens: projecten, werkitems, uren, Drive-documenten, klanten, facturen, verlof, planning en meer. De API spreekt JSON via HTTPS, op het eigen plnnrly-adres van je organisatie. ## Verbindingsgegevens | Instelling | Waarde | | ----------------- | ------------------------------------------------------------------------------ | | **Basis-URL** | `https:///api/v2` | | **Authenticatie** | `Authorization: Bearer ` | | **Formaat** | JSON. Stuur `Content-Type: application/json` mee bij elk verzoek met een body. | | **Contract** | [OpenAPI 3.1-document](https://developers.plnnrly.com/openapi.json) | Vervang `` door het adres waarop je in plnnrly inlogt, bijvoorbeeld `acme.plnnrly.com`. Gebruikt je organisatie een eigen domein, gebruik dan dat domein: de API antwoordt alleen op precies dat adres en stuurt nooit door. Er is geen gedeeld `api.plnnrly.com`. In plnnrly opent **API-toegang** in het gebruikersmenu de pagina **API-tokens**. Daar staat je basis-URL, klaar om te kopiëren. ## Twee manieren om je te authenticeren | Je bouwt | Gebruik | | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Scripts en koppelingen voor jezelf of je organisatie | Een persoonlijk token dat je in plnnrly aanmaakt. Zie [API-tokens (Engels)](https://developers.plnnrly.com/en/docs/api/v2/guides/tokens/). | | Een app die andere mensen installeren en waarin ze inloggen | Inloggen via OAuth: authorization code met PKCE, waarbij de app zichzelf registreert. Voor desktop- en commandoregelapps; wie inlogt, heeft het recht **API-tokens beheren** nodig. Zie [Inloggen met OAuth (Engels)](https://developers.plnnrly.com/en/docs/api/v2/guides/oauth-apps/). | In beide gevallen handelt elk verzoek namens één persoon, met diens rechten en niets meer. Apps die mensen via OAuth laten inloggen, kunnen via de REST API niets verwijderen. ## Een token aanmaken 1. Open in plnnrly **API-toegang** in het gebruikersmenu (rechtsboven, onder je naam) en kies **Token aanmaken**. 2. Geef het token een **Naam**. 3. Kies bij **Rechten** voor **Lezen**, **Schrijven** of **Verwijderen**. De lijst toont alleen wat je rol toestaat. Schrijven omvat lezen, en Verwijderen omvat schrijven en lezen. Het token slaat ze op als `api:read`, `api:write` en `api:destroy`, of per resource, zoals `api:read:projects`, als je **Onderdelen** invult. 4. Laat **Onderdelen** leeg om de tokenrechten voor alle onderdelen te laten gelden, of kies de delen van plnnrly waartoe het token beperkt blijft. De lijst toont alleen onderdelen waarvoor jij rechten hebt. 5. Vul **Verloopt op** in. Dit veld is verplicht, staat standaard op 90 dagen vanaf vandaag en mag maximaal 12 maanden vooruit liggen. 6. Kopieer het token. Het wordt maar één keer getoond. **API-toegang** staat alleen in het gebruikersmenu zolang de REST API aanstaat en jij het recht **API-tokens beheren** hebt. Zie [wie tokens mag aanmaken](https://developers.plnnrly.com/nl/docs/administration/#permissions). Je kunt tien actieve tokens tegelijk hebben. Het veld **Rechten** bevat de tokenrechten: wat het token mag. Dat is iets anders dan de rechten die je rol je geeft. Beide gelden, dus een token doet nooit meer dan jij in plnnrly kunt. [API-tokens (Engels)](https://developers.plnnrly.com/en/docs/api/v2/guides/tokens/) behandelt vernieuwen, intrekken en het volledige formulier. ## Bij elke operatie staat wat ervoor nodig is Elke operatiepagina in de [referentie (Engels)](https://developers.plnnrly.com/en/docs/api/v2/) noemt de tokenrechten en het plnnrly-recht die de operatie nodig heeft, en hoe zwaar ze meetelt voor de rate limit. De tokenrechten en het recht worden bij elk verzoek gecontroleerd. Aan het type van een `403` zie je waarom het verzoek is geweigerd: - [insufficient-token-scope](https://developers.plnnrly.com/en/docs/api/v2/guides/errors/#insufficient-token-scope): de tokenrechten dekken de operatie niet. Gebruik een token met ruimere rechten. - [insufficient-permission](https://developers.plnnrly.com/en/docs/api/v2/guides/errors/#insufficient-permission): je rol mist het recht. Vraag een beheerder om je rol aan te passen. - [forbidden-by-policy](https://developers.plnnrly.com/en/docs/api/v2/guides/errors/#forbidden-by-policy): je mag dit niet doen met dit specifieke record. ## Bekijk wat je organisatie aanbiedt Het [discovery-verzoek (Engels)](https://developers.plnnrly.com/en/docs/api/v2/discovery/) laat zien wat je organisatie aanbiedt: elke resource met zijn URL's en operaties. Elk persoonlijk API-token kan het aanroepen; er is geen recht voor nodig. ```bash curl https:///api/v2/ \ -H "Authorization: Bearer " \ -H "Accept: application/json" ``` De `Accept`-header is optioneel: laat hem weg, of stuur `application/json`. Discovery laat onderdelen weg die je organisatie niet gebruikt, zoals facturatie. Het controleert niet welke resources je tokenrechten of je rol dekken, dus een resource in de lijst kan toch `403` geven. ## Als de API uitstaat Een beheerder kan de REST API uitzetten onder **Instellingen › Beheer › MCP & API**. Zolang hij uitstaat, krijgt elk verzoek `404` [endpoint-not-found](https://developers.plnnrly.com/en/docs/api/v2/guides/errors/#endpoint-not-found), ook een verzoek met een token dat eerder werkte. Zie [wat er gebeurt als een schakelaar uitstaat](https://developers.plnnrly.com/nl/docs/administration/#when-switched-off). ## Verder lezen - [Aan de slag (Engels)](https://developers.plnnrly.com/en/docs/api/v2/guides/getting-started/): van een token tot je eerste wijziging. - [Overzicht van de referentie (Engels)](https://developers.plnnrly.com/en/docs/api/v2/): hoe de referentie is ingedeeld, en alle handleidingen. - [Fouten en opnieuw proberen (Engels)](https://developers.plnnrly.com/en/docs/api/v2/guides/errors/): elk probleemtype en wat je eraan doet. - [/openapi.json](https://developers.plnnrly.com/openapi.json): het hele contract, voor codegeneratoren en tools. ## Voor AI-assistenten Wil je een AI-assistent met je plnnrly-gegevens laten werken, gebruik dan de [MCP-server](https://developers.plnnrly.com/nl/docs/mcp/). Die bereikt dezelfde operaties als jij, behalve bestanden uploaden, en je hoeft er geen client voor te schrijven.