API-tokens

• Hvad er et API-token?
• Forudsætninger
• Hvor finder jeg API-tokens?
• Opret et token
• Tokenet vises kun én gang
• Hvad tokenlisten viser
• Tilbagekald et token
• Brug af tokenet

Hvad er et API-token?

Med Klubraum REST API’et kan jeres egne scripts, jeres klubhjemmeside eller andre værktøjer arbejde med klubbens kalenderbegivenheder og medlemmer. Hver forespørgsel identificerer sig med et personal access token, som du opretter i Klubraum-appen.

Sådan et token hører altid til én bestemt Klubraum og til den person, der har oprettet det. Det har kun de scopes, du giver det, det kan udløbe, og du kan tilbagekalde det når som helst. Og først og fremmest: et token kan aldrig mere end dig selv. Ved hver forespørgsel bliver dine aktuelle rettigheder i appen også kontrolleret. Mister du en rettighed, mister tokenet den også.

Forudsætninger

• Du er administrator i klubben. Andre medlemmer kan ikke se denne funktion.
• Jeres klub har en passende plan: medlemslisten, invitationer og fjernelse af medlemmer er inkluderet i Plus, alle andre endpoints kræver Pro. Uden en passende plan vises der en henvisning til opgradering, når du trykker på feltet.

Hvor finder jeg API-tokens?

Åbn Indstillinger, og gå til Nuværende Klubraum. Det andet felt hedder API-tokens med undertitlen Personal access tokens til Klubraum API’et – lige under feltet, hvor du ændrer klubbens navn.

OBS: Feltet lige nedenunder hører til tokenet til anmodninger om medlemskab. Det er et andet token, som kun er beregnet til medlemskabsformularen på jeres klubhjemmeside – du kan læse mere i Anmodning om medlemskab på klubbens hjemmeside.

Opret et token

Tryk på + øverst til højre (Opret token). Dialogen Opret API-token beder dig om tre ting.

Navn

Fri tekst på højst 100 tegn, for eksempel “Hjemmesidesynkronisering”. Giv hvert værktøj sit eget token, og opkald tokenet efter værktøjet – så ved du senere præcis, hvilket token du må tilbagekalde.

Scopes

Her bestemmer du, hvad tokenet må. Der findes fire scopes:

• members:read – læse medlemslisten.
• members:write – invitere og fjerne medlemmer.
• events:read – læse kalenderbegivenheder.
• events:write – oprette, ændre, aflyse og slette kalenderbegivenheder.

Et skrive-scope omfatter altid det tilsvarende læse-scope. Så snart du sætter flueben ved members:write, bliver members:read også sat automatisk og kan ikke længere fravælges; på tokenet gemmes så kun skrive-scopet. Det samme gælder for events:write og events:read. Der kræves mindst ét scope.

Tip: Vælg så få scopes som muligt. Et script, der kun viser jeres begivenheder på jeres hjemmeside, har blot brug for events:read.

Udløber efter

Vælg 30, 90, 180 eller 365 dage – eller Aldrig. Ved Aldrig vises der en advarsel, og med god grund: et token uden udløbsdato er gyldigt, indtil nogen tilbagekalder det. Giv derfor så vidt muligt tokenet en begrænset levetid.

Tryk derefter på Opret.

Tokenet vises kun én gang

Lige efter oprettelsen viser appen dig hele tokenet – den lange hemmelige tegnfølge, der begynder med klubraum_pat_. Kopiér den med kopiknappen, og gem den med det samme dér, hvor dit script eller værktøj læser den, helst i en adgangskodemanager eller et secrets-lager.

Vigtigt: Det er det eneste tidspunkt, hvor den hemmelige tegnfølge er synlig. Den kan ikke hentes frem senere, heller ikke af os. Mister du den, skal du tilbagekalde tokenet og oprette et nyt.

Læg aldrig den hemmelige tegnfølge et offentligt sted: ikke i JavaScript på jeres hjemmeside, ikke i et offentligt repository og ikke i en samtale i klubben. Den, der har den, kan bruge API’et med præcis de scopes, du har givet tokenet.

Hvad tokenlisten viser

På skærmen ser du alle tokens i jeres Klubraum. For hvert token finder du:

• det navn, du har givet det,
• et kort præfiks, der begynder med klubraum_pat_, og som identificerer tokenet uden at afsløre den hemmelige tegnfølge,
• scopes vist som chips,
• hvornår det blev oprettet, hvornår det udløber, og hvornår det sidst blev brugt.

På datoen for sidste brug kan du nemt se, hvilke tokens ingen længere har brug for. Tilbagekaldte tokens bliver stående på listen og vises med gennemstreget tekst.

Tilbagekald et token

Tryk på sletteikonet ved det pågældende token (Tilbagekald token), og bekræft med Ja, tilbagekald. Tilbagekaldelsen gælder med det samme: fra det øjeblik bliver enhver forespørgsel med dette token afvist. Det kan ikke fortrydes – et tilbagekaldt token kan ikke aktiveres igen.

Tip: Vil du udskifte et token, der stadig er i brug? Så opret først det nye token, skift dit script eller værktøj over til det, og tilbagekald først derefter det gamle.

Brug af tokenet

Send tokenet med hver forespørgsel som bearer token i Authorization-headeren:

Authorization: Bearer klubraum_pat_…

Hvilke endpoints der findes, hvilke parametre de forventer, og hvad de returnerer, står i udviklerafsnittet og i den interaktive API-reference. På engelsk.