Connect & Disconnect Flow

Overview

This guide explains how to implement the connect and disconnect flows for your published integration. When users discover your integration in Bokio, they can connect it to their company using OAuth 2.0 Authorization Code Flow.

Prerequisites:

• Registered Public API Integration with client_id and client_secret
• Published integration with ConnectRedirectUrl configured
• Understanding of OAuth 2.0 Authorization Code Flow

Connect Flow

How It Works

When a user clicks "Connect" on your integration:

1. Bokio redirects the user to your ConnectRedirectUrl
2. Your integration redirects to Bokio's /authorize endpoint
3. User authorizes your integration
4. Bokio redirects back with an authorization code
5. You exchange the code for tokens
6. User is redirected back to the integration page

Step 1: Handle Redirect from Bokio

Bokio redirects to your ConnectRedirectUrl with these query parameters:

Example:

https://your-integration.com/connect
  ?bokio_tenantid=1be29990-f977-4a62-bb03-f0e126e685d0
  &bokio_tenanttype=company
  &redirect_url=https://app.bokio.se/1be29990-f977-4a62-bb03-f0e126e685d0/integrations/your-integration-id

Step 2: Redirect to Bokio OAuth

Your endpoint should:

1. Generate a state parameter for CSRF protection
2. Store tenant info and redirect URL temporarily
3. Redirect to Bokio's /authorize endpoint

For full details on the OAuth flow, see Authentication for Public Integrations.

Authorization Request:

GET https://api.bokio.se/v1/authorize
  ?client_id=YOUR_CLIENT_ID
  &redirect_uri=YOUR_REDIRECT_URI
  &response_type=code
  &state=YOUR_GENERATED_STATE
  &scope=journal-entries:read invoices:read
  &bokio_tenantid=1be29990-f977-4a62-bb03-f0e126e685d0
  &bokio_tenanttype=company

📘

The state parameter is required by Bokio's OAuth implementation.

Step 3: Handle OAuth Callback

After user authorization, Bokio redirects to your redirect_uri:

https://your-integration.com/oauth/callback
  ?code=id2-4IE6ACIT5yIMB2ae5zVV4PrisE5-8q_ehKfezK4
  &state=YOUR_GENERATED_STATE

Your callback endpoint should:

1. Validate the state parameter (the one you generated in Step 2)
2. Exchange the authorization code for tokens (see Step 4)
3. Store the connection with tokens in your system
4. Redirect the user back to redirect_url (the Bokio URL from Step 1) - see Step 5

⚠️

Authorization Code Expiration: Codes expire in 5 minutes.

Step 4: Exchange Code for Tokens

POST https://api.bokio.se/v1/token HTTP/1.1
Authorization: Basic Base64(client_id:client_secret)
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=id2-4IE6ACIT5yIMB2ae5zVV4PrisE5-8q_ehKfezK4&redirect_uri=YOUR_REDIRECT_URI

Response:

{
  "connection_id": "abc12345-6789-...",
  "tenant_id": "1be29990-f977-4a62-bb03-f0e126e685d0",
  "tenant_type": "company",
  "access_token": "tffNhGDZ1FCpEWMkHduTA9FBnvNptzWSUfIlbcBHpdG5YJL",
  "token_type": "bearer",
  "expires_in": 3600,
  "refresh_token": "RpV4TYS8Z1KnJHpAqPJzXtl5QDl6OuK6NrQJk2FfLrGzKiM"
}

📘

Store the connection_id from this response. You will need it to manage the connection via the General API (e.g., when disconnecting).

📘

Token Expiration:

• Access tokens expire in 1 hour
• Refresh tokens expire when used or if unused for 30 days

Step 5: Redirect Back

After storing the connection, redirect to the redirect_url from Step 1. The user will see their integration as "Connected".

⚠️

Security: Always validate that the redirect_url points to a bokio.se domain before redirecting. This prevents open redirect attacks.

Disconnect Flow

Options

Bokio supports two disconnect options:

Option 1: Custom Disconnect (Recommended)

Configure a DisconnectRedirectUrl in your integration's publish information.

Flow:

1. User clicks "Disconnect" on your integration
2. Bokio redirects to your DisconnectRedirectUrl
3. Your integration processes the disconnect (optional cleanup)
4. Call the Bokio DELETE connection API (required)
5. Redirect to the callback_url with status

Disconnect URL Parameters

Example redirect to your integration:

https://your-integration.com/disconnect
  ?connectionId=abc12345-...
  &callback_url=https://api.bokio.se/api/publicintegration/disconnect-callback?...
  &state=STATE_VALUE

📘

Bokio includes a state parameter that must be passed back to the callback URL unchanged

Delete Connection API

Use the General API to delete the connection. First, obtain an access token using Client Credentials Grant.

Get Access Token:

POST https://api.bokio.se/v1/token HTTP/1.1
Authorization: Basic Base64(client_id:client_secret)
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials

Delete Connection:

DELETE https://api.bokio.se/v1/connections/{connectionId}
Authorization: Bearer {access_token}

Use the connection_id that you stored from the token response when the user connected.

Responses:

Redirect to Callback

After processing, redirect to the callback_url with a status parameter:

⚠️

Always validate that the callback_url points to a bokio.se domain before redirecting. This prevents open redirect attacks.

Additional Parameters:

• error: Error code (for error status)
• message: Detailed message for display

Example redirect:

{callback_url}?state={state-from-disconnect-redirect}&status=success

Or with error:

{callback_url}?state={state-from-disconnect-redirect}&status=error&error=api_error&message=Failed%20to%20delete%20connection

Option 2: Direct Disconnect

If you don't configure a DisconnectRedirectUrl, Bokio handles disconnection directly:

1. User clicks "Disconnect"
2. Bokio deletes the connection immediately
3. User sees updated connection status

Use this for simple integrations without cleanup requirements.

Connections API Reference

The General API provides endpoints to manage connections.

List Connections

GET https://api.bokio.se/v1/connections
Authorization: Bearer {access_token}

Query Parameters:

Response:

{
  "items": [
    {
      "id": "abc12345-...",
      "tenantId": "1be29990-...",
      "tenantName": "My Company AB",
      "type": "company"
    }
  ],
  "page": 1,
  "pageSize": 20,
  "totalItems": 1,
  "totalPages": 1
}

Get Connection by ID

GET https://api.bokio.se/v1/connections/{connectionId}
Authorization: Bearer {access_token}

Delete Connection by ID

DELETE https://api.bokio.se/v1/connections/{connectionId}
Authorization: Bearer {access_token}

Best Practices

Security

• Always validate the state parameter in OAuth callbacks
• Use HTTPS for all redirect URLs
• Store tokens securely with encryption at rest
• Exchange authorization codes immediately (5-minute expiry)
• Use Client Credentials Grant for General API access

User Experience

• Provide clear feedback during connect/disconnect
• Handle errors gracefully with user-friendly messages
• Always redirect back to the provided URLs
• Minimize friction in the connect flow

Implementation

• Store the connection_id from the token response - you need it for disconnect
• Test both connect and disconnect flows thoroughly
• Handle edge cases (expired codes, invalid tokens)
• Log connection events for debugging
• Support reconnection after disconnection
• Clean up resources properly during disconnect

Configuration Summary

Required

Optional

Error Handling

Connection Errors

Disconnection Errors

Related Documentation

• OAuth 2.0 Authentication
• General API Introduction
• Get Connections
• API Errors