Authenticate with Krebit Sign

Krebit Sign secures every request with OAuth 2.0 bearer tokens issued from your tenant at https://{organization}.krebit.se. Every REST endpoint lives beneath /api/1.0, and any call without a valid token is rejected with 401 Unauthorized.

This guide explains how to register OAuth applications, choose the right grant type, and keep tokens fresh so that follow-on guides (such as the Quickstart) work end to end.

Supported OAuth 2.0 grants

Krebit Sign supports two OAuth 2.0 grant types. Select the one that matches your integration pattern:

Flow	When to use it	Notes
Authorization Code	User-facing apps where an operator grants consent.	Returns both access and refresh tokens. Requires a registered redirect URI and CSRF-resistant state handling.
Refresh Token	Long-lived integrations that need to renew access tokens.	Exchange a refresh token for a new access token without prompting the user again.

Register an OAuth application

1. Sign in to https://{organization}.krebit.se/developer/my-apps.
2. Create a new application to obtain a client_id and client_secret. Secrets are shown only once—store them securely.
3. Add at least one redirect URI for the Authorization Code flow.
4. Record your tenant domain (for example, yourco.krebit.se) for use in token and API URLs.

Authorization Code example

1. Redirect the user to the authorization endpoint:

   https://{organization}.krebit.se/oauth/authorize?client_id={client_id}&redirect_uri={redirect_uri}&response_type=code&state={state}

   Use a cryptographically strong state value and persist it temporarily to mitigate CSRF attacks.

2. Handle the callback, validate state, and exchange the authorization code for tokens:

   curl --request POST \
     --url https://{organization}.krebit.se/api/oauth/token \
     --header 'Content-Type: application/json' \
     --data '{
       "grant_type": "authorization_code",
       "client_id": "YOUR_CLIENT_ID",
       "client_secret": "YOUR_CLIENT_SECRET",
       "redirect_uri": "https://yourapp.example.com/oauth/callback",
       "code": "AUTH_CODE_FROM_CALLBACK"
     }'

3. Persist the returned access_token, refresh_token, and expiry timestamp. Never expose tokens in client-side code or logs.

Refresh a token

Use the refresh token to obtain a new access token without prompting the user again:

curl --request POST \
  --url https://{organization}.krebit.se/api/oauth/token \
  --header 'Content-Type: application/json' \
  --data '{
    "grant_type": "refresh_token",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "refresh_token": "STORED_REFRESH_TOKEN"
  }'

Always replace the stored refresh token if the response includes a newer value.

Send authenticated API calls

Attach the bearer token to every request against the /api/1.0 prefix:

curl --request GET \
  --url https://{organization}.krebit.se/api/1.0/me \
  --header 'Authorization: Bearer eyJhbGciOi...'

Expect these status codes while integrating:

• 200 OK – Request succeeded.
• 401 Unauthorized – Token is missing, malformed, or expired.
• 403 Forbidden – The authenticated identity lacks permission to access the requested resource.

Security best practices

• Treat the client_secret, access tokens, and refresh tokens as sensitive credentials. Rotate them regularly.
• Use HTTPS for every request and enforce TLS 1.2 or higher in your HTTP client.
• Prefer short-lived access tokens cached in memory. Persist refresh tokens in an encrypted store with strict access controls.
• Log the request_id header (when present) for faster support collaboration, but avoid writing payloads containing personal data to logs.
• Validate redirect URIs and state parameters to block CSRF and open-redirect attacks.

Troubleshooting

• invalid_client – Confirm the client_id, client_secret, and tenant domain belong together.
• unsupported_grant_type – Double-check the grant_type value and ensure the JSON body includes every required field.
• invalid_grant during refresh – The refresh token may be expired or already used. Prompt the user to authenticate again.
• 403 responses – Ensure the authenticated user or integration has the correct roles for the resource you are targeting.

With authentication in place, continue to the Quickstart to create and send your first signing package.