OAuth — Connect with eFaktúra

For apps that act on behalf of eFaktúra users (e-shop, ERP, CRM, invoicing tool). The user signs in to eFaktúra, picks a company and approves what your app may do. You get a token bound to that company — nobody has to create or share an API key.

OAuth or API key?

Flow

1. Register your app (Dynamic Client Registration, once). List the Agent API in resources — without it you only get MCP tokens.

curl -X POST https://api.efaktura.sk/api/auth/oauth2/register \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "My e-shop",
    "redirect_uris": ["https://my-shop.example/efaktura/callback"],
    "token_endpoint_auth_method": "client_secret_basic",
    "grant_types": ["authorization_code", "refresh_token"],
    "response_types": ["code"],
    "resources": ["https://api.efaktura.sk/v1/agent"]
  }'

The response carries a client_id (and a client_secret for a server-side app). A mobile or desktop app uses "token_endpoint_auth_method": "none".

2. Send the user to consent. PKCE (S256) is required.

https://api.efaktura.sk/api/auth/oauth2/authorize
  ?response_type=code
  &client_id=<client_id>
  &redirect_uri=https://my-shop.example/efaktura/callback
  &scope=openid offline_access invoice:read invoice:create invoice:send
  &state=<random value>
  &code_challenge=<S256(code_verifier)>
  &code_challenge_method=S256
  &resource=https://api.efaktura.sk/v1/agent

The user signs in, picks a company and approves the scopes. We then send them back to redirect_uri with code and state.

3. Exchange the code for a token.

curl -X POST https://api.efaktura.sk/api/auth/oauth2/token \
  -u "<client_id>:<client_secret>" \
  -d grant_type=authorization_code \
  -d code=<code> \
  -d redirect_uri=https://my-shop.example/efaktura/callback \
  -d code_verifier=<code_verifier> \
  -d resource=https://api.efaktura.sk/v1/agent

4. Call the Agent API with the token. The company is in the token, so no X-Organization-Id is needed. If you send it, it must match.

curl https://api.efaktura.sk/v1/agent/invoices \
  -H "Authorization: Bearer <access_token>"

5. Refresh the token before it expires (valid for 1 h) with grant_type=refresh_token. You get a refresh token when you asked for the offline_access scope.

Technical parameters

The scope list is in API keys & scopes.

What a token may do

Errors