# Autentisering

API-nycklar för live och test, scopes, en nyckel per användare, rotation och OAuth för MCP-klienter.

Källa: https://getapi.gradientvibe.se/docs/autentisering

Varje anrop skickar en nyckel eller en OAuth-token i headern `Authorization`. Skicka den aldrig i URL:en.

```http
GET /api/v1/companies/569900-0013 HTTP/1.1
Host: getapi.gradientvibe.se
Authorization: Bearer gb_test_…
```

## API-nycklar

| Prefix | Miljö | Data | Kostnad |
| --- | --- | --- | --- |
| `gb_test_…` | Test | Sandlådan: påhittade bolag och personer | Gratis |
| `gb_live_…` | Live | Registret, levererat av Creditsafe | Enligt [prislistan](https://getapi.gradientvibe.se/docs/priser) |

- Du skapar nycklar under [Konto → Nycklar](https://getapi.gradientvibe.se/konto). Nyckeln visas **en gång**. Vi sparar bara en hash av den och kan inte visa den igen.
- Varje nyckel hör till en namngiven användare. Vi har inga tjänstenycklar som delas av flera. Ska en kollega använda API:t bjuder du in kollegan, som skapar en egen nyckel.
- När en användare tas bort från kontot slutar användarens nycklar och OAuth-anslutningar att fungera.
- Testnycklar fungerar så fort e-postadressen är bekräftad, även medan kontot granskas. Live-nycklar kräver ett godkänt konto och att live-data är öppnad.
- Prefixet `gb_` gör att en nyckel som hamnar i kod går att känna igen. Lägg nycklar i miljövariabler eller en hemlighetshanterare, aldrig i klientkod eller i ett repo.

## Scopes

En nyckel har ett eller flera scopes. Som standard får en ny nyckel alla. Ge en nyckel bara de scopes systemet behöver.

| Scope | Ger åtkomst till | Operationer |
| --- | --- | --- |
| `companies:read` | Sök och bolagsprofil | `search_companies`, `get_company`, `get_company_full` |
| `roles:read` | Styrelse, roller och firmateckning | `get_company_roles` |
| `history:read` | Historik och ändringar | `get_company_history` |
| `financials:read` | Bokslut och nyckeltal (AB) | `get_financials` |
| `persons:read` | Personers engagemang | `get_person_engagements` |

Ett anrop utan rätt scope ger `403 insufficient_scope`. `GET /api/v1/account` kräver inget scope.

## Byta och återkalla nycklar

1. Skapa en ny nyckel med samma scopes.
2. Byt nyckeln i ditt system och kontrollera att anropen går igenom.
3. Återkalla den gamla nyckeln under Konto → Nycklar. Den slutar fungera direkt.

Tror du att en nyckel har läckt: återkalla den först och skapa en ny sedan. Under Konto ser du när varje nyckel senast användes.

## Tak per nyckel

Du kan ge en nyckel ett eget dygnstak i kronor. När taket är nått svarar nyckeln `402 key_daily_cap_reached` resten av dygnet. Det är ett bra skydd för nycklar som en AI-agent använder. Se [takt och tak](https://getapi.gradientvibe.se/docs/takt-och-tak).

## OAuth för MCP-klienter

MCP-klienter som Claude och Cursor loggar in med OAuth 2.1 i stället för en nyckel. Du behöver inte göra något själv utom att logga in och godkänna åtkomsten. Det här är vad klienten gör:

1. Hämtar `https://getapi.gradientvibe.se/.well-known/oauth-protected-resource/mcp` och `https://getapi.gradientvibe.se/.well-known/oauth-authorization-server`.
2. Registrerar sig själv via `/oauth/register` (dynamisk klientregistrering).
3. Skickar dig till `/oauth/authorize`. Du loggar in på getBolag och ser kontot, klienten och vilka scopes den ber om. Du godkänner eller avböjer.
4. Hämtar token via `/oauth/token` med PKCE (S256).

| Token | Prefix | Giltig |
| --- | --- | --- |
| Access token | `gbo_at_…` | 1 timme |
| Refresh token | `gbo_rt_…` | 30 dagar. Byts vid varje användning; en gammal refresh token ger `invalid_grant`. |

- Scopes för OAuth är desamma som för nycklar.
- En OAuth-anslutning hör till användaren som godkände den, och räknas som live. Medan live-data inte är öppnad svarar den `blocked_by_phase`; använd då en testnyckel som header, se [MCP](https://getapi.gradientvibe.se/docs/mcp#nyckel).
- Du ser och återkallar anslutna klienter under Konto. Klienten kan också återkalla sin token via `/oauth/revoke`.