Authentication

Our API supports two primary authentication methods to secure your requests: bearer tokens for simple authentication and OAuth 2.0 flows for more complex integrations.

Bearer Token Authentication

Bearer tokens provide a straightforward way to authenticate API requests. Include your token in the Authorization header of each request.

Getting your bearer token

Log into your dashboard
Navigate to API Settings
Generate a new API token
Copy and securely store your token

Keep your bearer tokens secure and never expose them in client-side code or public repositories.

Using bearer tokens

Include your bearer token in the Authorization header:

curl -X GET 'https://api.example.com/users' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

OAuth 2.0 Authentication

OAuth 2.0 provides secure authorization for applications that need to access user data. We support multiple OAuth flows:

Authorization Code flow: For web applications accessing their own data
Connected Accounts flow: For third-party platforms accessing customer data on their behalf

OAuth flow overview

Redirect user for authorization

Redirect users to our authorization endpoint with your client ID and desired scopes.

https://accounts.proconvey.co.uk/oauth/authorize?
  client_id=YOUR_CLIENT_ID&
  redirect_uri=YOUR_REDIRECT_URI&
  response_type=code&
  scope=read write

Handle the callback

After user authorization, we’ll redirect to your callback URL with an authorization code.

Exchange code for access token

Exchange the authorization code for an access token using your client credentials.

curl -X POST 'https://v2.proconvey.co.uk/oauth/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=authorization_code&
      code=AUTHORIZATION_CODE&
      client_id=YOUR_CLIENT_ID&
      client_secret=YOUR_CLIENT_SECRET&
      redirect_uri=YOUR_REDIRECT_URI'

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "def50200..."
}

Use the access token

Include the access token in your API requests:

curl -X GET 'https://v2.proconvey.co.uk/users' \
  -H 'Authorization: Bearer ACCESS_TOKEN'

Refreshing tokens

Access tokens expire after a certain period. Use the refresh token to obtain new access tokens:

curl -X POST 'https://v2.proconvey.co.uk/oauth/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=refresh_token&
      refresh_token=YOUR_REFRESH_TOKEN&
      client_id=YOUR_CLIENT_ID&
      client_secret=YOUR_CLIENT_SECRET'

OAuth Connected Accounts

OAuth Connected Accounts enable third-party platforms to access ProConvey on behalf of their customers, similar to Stripe Connect. This allows platforms to integrate ProConvey functionality while maintaining proper authorization and data isolation.

How Connected Accounts Work

Connected Accounts use a combination of machine-to-machine authentication for the platform and OAuth authorization for customer consent:

Platform Authentication: Third-party platforms use machine-to-machine tokens to authenticate themselves
Customer Authorization: Customers authorize the platform to access their ProConvey account via OAuth
API Access: Platforms make API requests using the ProConvey-Account header to specify which customer account to act on behalf of

Setting Up Connected Accounts

Platform Registration

Contact our partnership team to register your platform and receive your client_id and client_secret.

Customer Authorization Flow

Direct customers to authorize your platform to access their ProConvey account:

https://accounts.proconvey.co.uk/oauth/authorize?
  client_id=YOUR_CLIENT_ID&
  redirect_uri=YOUR_REDIRECT_URI&
  response_type=code&
  scope=read write&
  state=CSRF_TOKEN

Always include a state parameter for CSRF protection and to track the authorization request.

Token Exchange

Exchange the authorization code for access tokens that represent the connected account:

curl -X POST 'https://v2.proconvey.co.uk/oauth/token' \
  -H 'Content-Type: application/json' \
  -d '{
    "grant_type": "authorization_code",
    "code": "AUTHORIZATION_CODE",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "redirect_uri": "YOUR_REDIRECT_URI"
  }'

{
  "access_token": "pca_1234567890abcdef...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "pcr_abcdef1234567890...",
  "scope": "read write",
  "connected_account_id": "conn_abc123xyz789",
  "organisation_id": "org_customer123"
}

Making API Requests

Use the access token and connected account ID to make API requests on behalf of the customer:

curl -X GET 'https://v2.proconvey.co.uk/v2/cases' \
  -H 'Authorization: Bearer pca_1234567890abcdef...' \
  -H 'ProConvey-Account: conn_abc123xyz789'

ProConvey-Account Header

The ProConvey-Account header is required when making API requests on behalf of a connected account. This header:

Identifies which customer account the request should act on behalf of
Ensures proper data isolation between different customer accounts
Enables audit logging of platform actions

The ProConvey-Account header value is the connected_account_id returned during the token exchange process.

Token Management for Connected Accounts

Connected account tokens work similarly to standard OAuth tokens but include additional metadata:

Token Refresh

curl -X POST 'https://v2.proconvey.co.uk/oauth/token' \
  -H 'Content-Type: application/json' \
  -d '{
    "grant_type": "refresh_token",
    "refresh_token": "pcr_abcdef1234567890...",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET"
  }'

{
  "access_token": "pca_new1234567890abcdef...",
  "token_type": "Bearer", 
  "expires_in": 3600,
  "refresh_token": "pcr_newabcdef1234567890...",
  "scope": "read write"
}

Token Security

Access tokens are prefixed with pca_ and expire after 1 hour
Refresh tokens are prefixed with pcr_ and have longer lifespans
All tokens are hashed using SHA-256 before storage
Implement proper token rotation and secure storage practices

Scopes

OAuth tokens can be limited to specific scopes to control access levels. Connected Accounts support granular permissions for fine-grained access control:

Standard Scopes

Scope	Description
`read`	Read access to user data
`write`	Write access to create and modify data
`admin`	Administrative access to account settings

Granular Scopes (Connected Accounts)

For Connected Accounts, you can request more specific permissions:

Scope	Description
`read:cases`	Read access to case data
`write:cases`	Create and modify case data
`read:quotes`	Read access to quote information
`write:quotes`	Create and modify quotes
`read:contacts`	Read access to contact information
`write:contacts`	Create and modify contact data
`read:documents`	Read access to documents
`write:documents`	Upload and modify documents
`read:reports`	Read access to reports and analytics

Request only the minimum scopes required for your integration. This follows the principle of least privilege and builds trust with your customers.

Security Considerations for Connected Accounts

When implementing Connected Accounts, follow these security best practices:

Token Storage and Management

Store all tokens securely using encryption at rest
Never log or expose tokens in error messages or debugging output
Implement automatic token rotation before expiration
Use secure, HTTPs-only endpoints for all OAuth flows

Access Control

Regularly audit connected account permissions and usage
Implement IP allowlisting for production integrations
Monitor for unusual API usage patterns that might indicate compromise
Provide customers with visibility into platform access and usage

Data Isolation

The API automatically enforces data isolation by validating that the ProConvey-Account header corresponds to an organization the authenticated platform has permission to access.

Audit and Compliance

All Connected Account API usage is automatically logged for audit purposes, including:

OAuth authorization events
Token exchanges and refreshes
API requests with associated connected account IDs
Permission changes and revocations

Rate Limiting

Connected Accounts are subject to rate limiting based on:

Per-platform limits across all connected accounts
Per-connected-account limits for individual customer protection
Scope-specific limits for different types of operations

Implement exponential backoff and retry logic to handle rate limiting gracefully. Monitor your usage via the platform dashboard to optimize performance.

Error handling

Common authentication errors and how to handle them:

401 Unauthorized

Cause: Invalid or missing authentication credentialsSolution: Verify your token is correct and included in the Authorization header

403 Forbidden

Cause: Valid credentials but insufficient permissionsSolution: Check that your token has the required scopes for the endpoint

Token expired

Cause: Access token has exceeded its expiration timeSolution: Use your refresh token to obtain a new access token

Invalid connected account

Cause: The ProConvey-Account header references an invalid or inactive connected accountSolution: Verify the connected account ID is correct and the connection is still active

Domain mismatch

Cause: The connected account doesn’t match the API domain being accessedSolution: Ensure you’re making requests to the correct API domain for the connected account

Connection revoked

Cause: The customer has revoked authorization for your platformSolution: Re-initiate the OAuth flow to obtain new authorization from the customer

Best practices

General Authentication

Store tokens securely using environment variables or secure credential management
Implement token refresh logic to handle expired tokens gracefully
Use the minimum required scopes for your application
Regularly rotate your API keys and OAuth credentials

Connected Accounts

Always include the ProConvey-Account header when making requests on behalf of customers
Implement proper error handling for connection-specific errors
Monitor token usage and implement proactive refresh strategies
Provide clear consent flows that explain what data your platform will access
Regularly audit connected account permissions and remove unused connections
Use webhook notifications to handle account disconnections gracefully

Testing authentication

Standard Authentication

You can test your authentication setup using our API explorer or by making a simple request to the /me endpoint:

curl -X GET 'https://v2.proconvey.co.uk/me' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Connected Accounts Testing

Test Connected Account access by making a request with the ProConvey-Account header:

curl -X GET 'https://v2.proconvey.co.uk/v2/me' \
  -H 'Authorization: Bearer pca_your_access_token' \
  -H 'ProConvey-Account: conn_your_connected_account_id'

A successful response confirms your Connected Account authentication is working correctly and will include information about the customer’s organization.

Use our sandbox environment for testing Connected Accounts integration before going live. Contact our support team to set up sandbox credentials.

Organisations

Cases

Accounts

System

Webhooks

Bearer Token Authentication

Getting your bearer token

Using bearer tokens

OAuth 2.0 Authentication

OAuth flow overview

Refreshing tokens

OAuth Connected Accounts

How Connected Accounts Work

Setting Up Connected Accounts

ProConvey-Account Header

Token Management for Connected Accounts

Token Refresh

Token Security

Scopes

Standard Scopes

Granular Scopes (Connected Accounts)

Security Considerations for Connected Accounts

Token Storage and Management

Access Control

Data Isolation

Audit and Compliance

Rate Limiting

Error handling

Best practices

General Authentication

Connected Accounts

Testing authentication

Standard Authentication

Connected Accounts Testing

Organisations

Cases

Accounts

System

Webhooks

​Bearer Token Authentication

​Getting your bearer token

​Using bearer tokens

​OAuth 2.0 Authentication

​OAuth flow overview

​Refreshing tokens

​OAuth Connected Accounts

​How Connected Accounts Work

​Setting Up Connected Accounts

​ProConvey-Account Header

​Token Management for Connected Accounts

​Token Refresh

​Token Security

​Scopes

​Standard Scopes

​Granular Scopes (Connected Accounts)

​Security Considerations for Connected Accounts

​Token Storage and Management

​Access Control

​Data Isolation

​Audit and Compliance

​Rate Limiting

​Error handling

​Best practices

​General Authentication

​Connected Accounts

​Testing authentication

​Standard Authentication

​Connected Accounts Testing

Bearer Token Authentication

Getting your bearer token

Using bearer tokens

OAuth 2.0 Authentication

OAuth flow overview

Refreshing tokens

OAuth Connected Accounts

How Connected Accounts Work

Setting Up Connected Accounts

ProConvey-Account Header

Token Management for Connected Accounts

Token Refresh

Token Security

Scopes

Standard Scopes

Granular Scopes (Connected Accounts)

Security Considerations for Connected Accounts

Token Storage and Management

Access Control

Data Isolation

Audit and Compliance

Rate Limiting

Error handling

Best practices

General Authentication

Connected Accounts

Testing authentication

Standard Authentication

Connected Accounts Testing