De openbare API van Escher V2 (/v1/*) vereist een Bearer-token bij elk verzoek. Maak tokens aan en beheer ze op de pagina API tokens — open het accountmenu linkonder in de zijbalk en kies API tokens (/settings/api-tokens).
Je hebt eerst API-toegang nodig
API-tokens zijn beperkt beschikbaar. Op de pagina kun je alleen tokens aanmaken als API-toegang voor je account is ingeschakeld.
Als dat niet het geval is, wordt het volgende bericht weergegeven:
API-toegang is niet ingeschakeld voor je account. Neem contact op met je accountmanager via support@theprintspace.co.uk om dit aan te vragen.
Stuur een e-mail naar support@theprintspace.co.uk om het in te schakelen en kom dan terug naar deze pagina.
Wie heeft API-tokens nodig
- Artiesten die aangepaste integraties bouwen (bijvoorbeeld een portfoliosite die drops op aanvraag start).
- Agentschappen die meerdere artiestaccounts via automatisering beheren.
- Ontwikkelaars die interne tools bouwen die met de API communiceren.
Als je alleen de webinterface gebruikt om drops handmatig aan te maken, heb je geen token nodig.
Hoe maak je een token aan
- Open de pagina API tokens (accountmenu → API tokens).
- Voer een Token name in (de plaatsaanduiding in het veld luidt "Token name (e.g. 'Backend CI')") zodat je het later kunt herkennen.
- Voer optioneel een Webhook URL in — zie hieronder. De plaatsaanduiding in het veld luidt "Webhook URL (optional, https://…)"; laat het leeg of voer een volledige
https://-URL in. - Klik Generate token.
- Het volledige token wordt eenmalig weergegeven, met de opmerking "Copy this token now — it will never be shown again." Kopieer het onmiddellijk.
- Bewaar het veilig — in een secrets manager, je CI/CD-omgeving of een
.env-bestand buiten versiebeheer.
Nieuwe tokens verschijnen in de lijst met deze kolommen: Name, Prefix, Webhook, Created, Last used. Alleen het voorvoegsel wordt opgeslagen — het volledige token kan na het aanmaken niet meer worden opgehaald.
Optionele webhook-URL
Elk token kan een optionele https://-webhook-URL bevatten. Stel deze in wanneer je het token aanmaakt, of pas het later aan: klik op het potloodpictogram naast de Webhook-cel van een token, voer een volledige https://-URL in (of wis deze) en sla op.
Wat je met het token kunt doen
Het volledige /v1-oppervlak wordt gedocumenteerd op het OpenAPI-eindpunt (/openapi.json op de API-service). Veelgebruikte bewerkingen:
- Drops aanmaken —
POST /v1/drops. - Producten aan drops toevoegen —
POST /v1/drops/{drop_id}/products. - Varianten configureren —
PUT /v1/drops/{drop_id}/products/{product_id}/variants. - Publicatie activeren —
POST /v1/drops/{drop_id}/publish. - Publicatiestatus controleren —
GET /v1/drops/{drop_id}/publish-attempts/latest. - Aanbevelingen genereren —
POST /v1/recommendations. - Paginastijlen uit een URL extraheren —
POST /v1/styles/extract(retourneert vijf variaties om uit te kiezen). - Een paginastijl-voorinstelling opslaan —
POST /v1/styles.
Authenticatie
Geef het token als Bearer-header door bij elk verzoek:
Authorization: Bearer <your-token>
Een ontbrekend, ingetrokken of ongeldig token retourneert HTTP 401. Als API-toegang voor het account is uitgeschakeld, krijg je HTTP 403.
Snelheidslimieten
- Lees-eindpunten: 120 verzoeken per minuut per gebruiker.
- Schrijf-eindpunten: 30 verzoeken per minuut per gebruiker.
Overschreden aanroepen retourneren HTTP 429 met een Retry-After-header. De limieten zijn per gebruiker, niet per token, dus meerdere tokens voor dezelfde gebruiker delen dezelfde bucket.
Token-levenscyclus
- Intrekken — klik op de knop Revoke op de rij van het token en bevestig het dialoogvenster ("Revoke … This cannot be undone and the token will stop working immediately."). Toekomstige verzoeken met dat token retourneren 401.
- Roteren — maak een nieuw token aan, wissel je integratie over naar dit token en trek het oude in. Geen downtime als je dit in de juiste volgorde doet.
- Vervaldatum — tokens verlopen niet automatisch. Roteer elke 6–12 maanden als onderdeel van je beveiligingshygiëne.
Niet delen
Tokens zijn volledige referenties — iedereen die er een heeft, kan namens jou op het platform handelen, inclusief het publiceren van drops en het bewerken van producten. Behandel ze met dezelfde voorzichtigheid als een wachtwoord.