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 flow, and keep tokens fresh so that follow-on guides (such as the Quickstart) work end to end.

Supported OAuth 2.0 flows

Krebit Sign supports two standard flows. Select the one that matches your integration pattern:

Flow	When to use it	Notes
Client Credentials	Server-to-server jobs, backend automation, or internal admin tooling.	Issues app-only tokens. No refresh token is returned—request a new access token when the current one expires.
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.

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 if you intend to use the Authorization Code flow.
4. Record your tenant domain (for example, yourco.krebit.se) for use in token and API URLs.

Client Credentials example

Exchange client credentials for an access token using JSON. Replace placeholders with values from your tenant.

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

Example response:

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

Store the access_token in memory or a secure secret store and attach it to subsequent API calls. When expires_in elapses, request another token with the same client credentials.

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/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/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.