Åpent API

 

Innholdsfortegnelse

• Les dette først
• Roller og tilgang
• Hva er Open API?
• Hvilke data er tilgjengelige?
• Hvor du finner det
• Opprette en API-nøkkel
• Administrere API-nøkler
• Autentisering
• API-dokumentasjon
• Ofte stilte spørsmål

 

 

---

 

📖 Les dette først

Før du oppretter en API-nøkkel, bør du lese «Roller og tilgang for API-nøkler». Der står det steg for steg hvordan du oppretter en nøkkel og gir den tilgangen den trenger.

🔗 Les om roller og tilgang for API-nøkler.

 

 

Roller og tilgang

Rolle	Tilgang
Administratorer med tilgang til Systeminnstillinger	Kan opprette, redigere, deaktivere og slette API-nøkler

 

💡 For å koble et system til Open API trenger API-nøkkelen roller. Rollene bestemmer hva nøkkelen kan lese og endre i Huma. For å gi en nøkkel roller trenger du selv en egen systemrolle.

🔗 Les om API-nøkler og tilgang for å se hvordan du gir en API-nøkkel tilgang, og hva som gjelder for nøkler som er opprettet før september 2026.

🔗 Se Roller i Huma for å lese mer om hvordan roller fungerer.

 

 

 

Hva er Åpent API?

Open API er Humas REST API. Med det kan du hente og oppdatere data i Huma programmatisk, fra egne systemer eller integrasjoner.

Open API fungerer annerledes enn webhooks. Med webhooks sender Huma data til deg automatisk hver gang noe endres. Med Open API henter eller sender du data selv, når du vil.

🔗 Se Webhooks for å lese mer om hvordan automatiske oppdateringer fra Huma fungerer.

 

 

 

Hvilke data er tilgjengelige?

Med Open API får du tilgang til data om ansatte og organisasjonen i Huma. Denne seksjonen gir deg en oversikt over hva du kan hente og oppdatere. Da kan du vurdere om Open API dekker behovene deres.

💡 For å sette opp en integrasjon med Open API trenger du teknisk kompetanse. Den som setter den opp, bør kunne lese den tekniske API-dokumentasjonen. Har dere ikke denne kompetansen internt, kan dere be IT-partneren eller systemleverandøren deres om hjelp.

⚠️ Hva en API-nøkkel kan se og endre, avhenger av rollene du gir den. Et felt i listen under er bare tilgjengelig hvis nøkkelen har tilgang til det.

🔗 Les om API-nøkler og tilgang for å se hvordan du gir en API-nøkkel roller.

 

Ansatte

Du kan hente, opprette og oppdatere ansatte.

Område	Felter
Grunnleggende informasjon	Fornavn, Etternavn, Foretrukket navn, E-postadresse, Personlig e-postadresse, Telefonnummer
Personlig informasjon	Fødselsdato, Kjønn, Nasjonalitet, Sivilstatus, Adresse
Arbeid	Ansettelses-ID, Nærmeste leder, Teams, Lokasjoner, Selskaper, Relevant erfaring, Ansiennitetsnotat
Økonomi	Bankkonto
Annet	Kostbehov, Interesser, Morsomme fakta, Ekskluder fra Innsikter, Ekskluder fra eNPS-undersøkelser, Egendefinerte felter

💡 Når du oppretter en ansatt, kan du også velge å sende en invitasjon til Huma samtidig.

 

Stillinger

Du kan hente, opprette, oppdatere og fjerne stillingene til en ansatt.

Område	Felter
Stillinger	Stillingstittel, Individuell stillingsbeskrivelse, Kontrakttype, Stillingsprosent, Startdato for kontrakt, Første arbeidsdag, Sluttdato for prøvetid, Land / Lovgivning, Merknader, Dato oppsigelsen ble levert, Siste arbeidsdag, Sluttdato for kontrakt, Sluttdetaljer (årsak og merknad)

 

 

Barn, nødkontakter og identifikasjon

Du kan legge til, oppdatere og fjerne disse for en ansatt. De hentes sammen med den ansatte.

Område	Felter
Barn	Navn, Fødselsdato
Nødkontakt	Navn, Telefonnummer, Relasjon
Identifikasjon	Type (fødselsnummer eller pass), Land, Nummer

 

Grupper og stillingstitler

Område	Hva du kan gjøre	Felter
Teams, lokasjoner og selskaper	Hente, opprette og oppdatere	Navn, Beskrivelse, Lenker. Lokasjoner og selskaper har også adresse. Selskaper har også organisasjonsnummer.
Stillingstitler	Hente, opprette og oppdatere	Navn, Beskrivelse

 

 

Kun lesetilgang

Disse dataene kan du hente, men ikke endre via Open API:

• Arbeidsplan for en ansatt
• Jubileer
• Offentlige helligdager per land
• Gjeldende lønn slik den står på profilen til den ansatte (beløp, periode og valuta). Bare tilgjengelig hvis organisasjonen bruker lønnsmodulen og API-nøkkelen har tilgang til lønn. Lønnshistorikk og lønnsrevisjoner er ikke tilgjengelig via Open API.
  
  

 

🔗 Se API-dokumentasjonen for tekniske detaljer om hvert felt.

 

 

 

 

Hvor finner du det?

Du finner Open API slik:

1. Gå til «Systeminnstillinger»
2. Velg «Open API» i menyen til venstre

 

⛓️‍💥 API-dokumentasjon: https://openapi.humahr.com/redoc/index.html

 

 

 

Opprette en API-nøkkel

1. Gå til «Systeminnstillinger» og «Open API»
2. Klikk «Legg til API-nøkkel»
3. Gi nøkkelen et navn, og legg eventuelt til en beskrivelse
4. Klikk «Lagre»
5. Når nøkkelen er opprettet, vises «Client ID» og «Client secret» ⚠️ Ta vare på «Client secret» på et trygt sted.
6. Lukk vinduet. Nøkkelen åpnes i listen, slik at du kan gi den tilgang med en gang

 

⚠️ Merk

• Ta vare på «Client secret» på et trygt sted. Du får ikke se den igjen. Beskytt API-nøkkelen, fordi alle som har den, kan lese eller endre dataene til organisasjonen. Hvis du mister «Client secret», må du opprette en ny API-nøkkel.

• En ny API-nøkkel har ingen tilgang. Den kan ikke lese eller endre noe før du har gitt den minst én rolle.

 

🔗 Les om API-nøkler og tilgang for å se hvordan du gir nøkkelen tilgang.

 

 

 

Administrere API-nøkler

Du kan ha flere API-nøkler samtidig. Klikk på de tre prikkene ved siden av en nøkkel for å:

• Redigere API-nøkkel: Endre navn, ikon og beskrivelse på en eksisterende nøkkel.
• Deaktivere API-nøkkel: Nøkkelen deaktiveres med en gang, men beholder rollene sine. Du kan aktivere den igjen på samme sted.
• Slette: ⚠️ API-nøkkelen slettes med en gang og kan ikke gjenopprettes. Alle forespørsler som gjøres med den, blir avvist. Det kan stoppe systemer som er avhengige av tilgang til Open API.

 

 

 

 

Autentisering

OAuth2 Client Credentials: slik henter og bruker du et tilgangstoken

Denne veiledningen viser hvordan du autentiserer med OAuth2 og «client_credentials», og hvordan du bruker tilgangstokenet med Humas API.

🔑 Endepunkt for token: https://demo.openapi.humahr.com/auth/oauth/token

 

Oversikt

• Grant type: client_credentials
• Inndata: client_id og client_secret (utstedt av Huma)
• Utdata: JSON med access_token, token_type (Bearer) og expires_in (sekunder)
• Bruk: Send tokenet i headeren Authorization: Bearer <token> i API-forespørslene

 

Forutsetninger

Du har en client_id og en client_secret fra Huma. Hold denne påloggingsinformasjonen trygt.

 

Miljøvariabler

For enkelhets skyld kan du sette endepunktet for token én gang og bruke det i kommandoene:

export TOKEN_URL="https://demo.openapi.humahr.com/auth/oauth/token" 

 

Be om et token

Med curl og application/x-www-form-urlencoded

Be om et token med en body i formatet application/x-www-form-urlencoded:

# Bytt ut plassholderne med din egen påloggingsinformasjon CLIENT_ID="your-client-id" CLIENT_SECRET="your-client-secret"  curl -sS \   -X POST "${TOKEN_URL}" \   -H "Content-Type: application/x-www-form-urlencoded" \   --data-urlencode "grant_type=client_credentials" \   --data-urlencode "client_id=${CLIENT_ID}" \   --data-urlencode "client_secret=${CLIENT_SECRET}" 

Med curl og application/json

Be om et token med en body i formatet application/json:

CLIENT_ID="your-client-id" CLIENT_SECRET="your-client-secret"  curl -sS \   -X POST "${TOKEN_URL}" \   -H "Content-Type: application/json" \   -d "{\"grant_type\":\"client_credentials\",\"client_id\":\"$CLIENT_ID\",\"client_secret\":\"$CLIENT_SECRET\"}" 

💡 Merk: Serveren støtter både application/x-www-form-urlencoded og application/json for forespørselen om token. Velg det som passer verktøyet ditt.

Et vellykket svar ser slik ut:

{   "token_type": "Bearer",   "access_token": "eyJhbGciOi...",   "refresh_token": "def50200...",   "expires_in": 3600 } 

 

Bruke tilgangstokenet

Legg tokenet i headeren «Authorization» i API-forespørslene:

ACCESS_TOKEN="eyJhbGciOi..." # fra svaret med tokenet  curl -sS \   -H "Authorization: Bearer ${ACCESS_TOKEN}" \   -H "Accept: application/json" \   "https://demo.openapi.humahr.com/users" 

 

Referanser

⛓️‍💥 OAuth 2.0 (RFC 6749), avsnitt 4.4: Client Credentials Grant

⛓️‍💥 OAuth 2.0 (RFC 6749), avsnitt 6: Refreshing an Access Token

 

 

 

 

API-dokumentasjon

Klikk «Se Open API-dokumentasjon» på siden for Open API for å se den fullstendige tekniske dokumentasjonen direkte i Huma. Der finner du detaljer om endepunkter, formater for forespørsler og svar, datatyper og feilkoder.

Du kan velge mellom to visninger:

• Redoc: en lettlest oversikt over alle endepunktene
• Swagger: en interaktiv visning der du kan teste forespørsler direkte

💡 Du kan også klikke «Åpne i et nytt vindu eller en ny fane» for å se dokumentasjonen i et eget vindu.

Dokumentasjonen er delt inn i ressursgrupper, blant annet Authentication, Group, Holiday, Job Title, Position, User, User Child, User Emergency Contact og User Identification.

 

⛓️‍💥 API-dokumentasjon.

 

 

 

Ofte stilte spørsmål

Hvordan får jeg tilgang til Open API?

Gå til Systeminnstillinger → Open API og klikk «Legg til API-nøkkel». Du trenger administratortilgang til Systeminnstillinger. Gi deretter nøkkelen rollene den trenger. Les om API-nøkler og tilgang for å se hvordan.

 

Hva skjer hvis jeg mister client_secret?

Du kan ikke hente den frem igjen. Da må du opprette en ny API-nøkkel.

 

Hva er forskjellen på å deaktivere og å slette en API-nøkkel?

Deaktivering kan angres, og du kan aktivere nøkkelen igjen senere. Sletting skjer med en gang og er permanent, og alle forespørsler som gjøres med den slettede nøkkelen, blir avvist.

 

Hva er forskjellen på Open API og webhooks?

Webhooks sender data til deg automatisk når noe skjer i Huma. Med Open API henter eller sender du data selv, når du vil, ved å sende forespørsler til API-et.

 

Hva er forskjellen på Redoc og Swagger i dokumentasjonen?

Redoc gir en lettlest oversikt over endepunktene. I Swagger kan du teste forespørsler direkte i dokumentasjonen.

 

Kan jeg se en liste over feltene uten å lese den tekniske dokumentasjonen?

Ja. Se seksjonen «Hvilke data er tilgjengelige?» i denne artikkelen. Der får du en oversikt over dataene du kan hente og oppdatere.

 

Kan jeg slette eller deaktivere ansatte via Open API?

Nei. Du må slette, deaktivere og aktivere ansatte på nytt i Huma.

 

Hvorfor ser ikke API-nøkkelen alle feltene?

Nøkkelen kan bare se og endre data den har tilgang til gjennom rollene sine. Sjekk hvilke roller nøkkelen har under Systeminnstillinger → Open API.