OAuth vs API Key Authentication
Otesse supports two authentication methods for third-party integrations: OAuth 2.0 with PKCE and manual API key entry. The authentication type is determined by the provider — each provider in the catalog specifies which method it uses. This page explains how each method works, their security characteristics, and how credentials are managed.
OAuth 2.0 with PKCE
OAuth is the industry standard for delegated authorization. When a provider supports OAuth, the user authenticates directly with the provider (not through Otesse) and grants Otesse specific permissions (scopes) to access their account.
How OAuth Works
- State creation — The system generates a cryptographically random state token and a PKCE code verifier/challenge pair. These are stored in an
OauthStaterecord that expires after 10 minutes.
- Authorization redirect — The user's browser is redirected to the provider's authorization page with the following parameters:
| Parameter | Description |
|---|---|
client_id | Otesse's application ID with the provider |
redirect_uri | Callback URL where the provider sends the user after authorization |
response_type | Always "code" (authorization code flow) |
state | Random token for CSRF protection |
code_challenge | SHA-256 hash of the code verifier (PKCE) |
scope | Permissions being requested |
- User grants access — The user sees the provider's consent screen listing what Otesse is requesting access to. They click "Allow" or "Deny."
- Callback processing — The provider redirects back to Otesse with an authorization code. The system validates the state token, exchanges the code for access/refresh tokens using the PKCE code verifier, and stores the tokens encrypted.
- Health check — The system uses the new access token to make a test API call, verifying the connection works.
OAuth Security Features
| Feature | Purpose |
|---|---|
| PKCE (Proof Key for Code Exchange) | Prevents authorization code interception attacks |
| State token | Prevents cross-site request forgery (CSRF) |
| 10-minute expiry | State tokens expire quickly to limit attack window |
| Single-use state | Each state token can only be used once |
| Server-side code verifier | The PKCE verifier is never sent to the browser |
Token Lifecycle
OAuth connections involve two types of tokens:
| Token | Lifetime | Purpose |
|---|---|---|
| Access token | Short-lived (typically 1 hour) | Used for API calls to the provider |
| Refresh token | Long-lived (months or indefinite) | Used to obtain new access tokens when the current one expires |
When an access token expires, the system automatically attempts to refresh it using the refresh token. If the refresh fails (token revoked or expired), the connection status changes to "expired" and the user must re-authenticate.
API Key Authentication
API key authentication is simpler — the user manually enters their API key (and optionally an API secret or account ID) into a form. The key is encrypted and stored immediately.
How API Key Auth Works
- Form display — A modal shows input fields based on the provider's
requiredCredentialsconfiguration. Most providers need only an API key; some require additional fields.
- Credential entry — The user enters their credentials. All fields are masked (password-type inputs) to prevent shoulder surfing.
- Encryption — On submission, each credential is encrypted using AES-256-GCM with a key derived from the
INTEGRATIONENCRYPTIONKEYenvironment variable.
- Storage — Encrypted credentials are stored in
IntegrationCredentialrecords. The plaintext is never logged, never stored in the database, and never included in API responses.
- Health check — The system decrypts the credentials and makes a test API call to verify they work.
API Key Security Features
| Feature | Purpose |
|---|---|
| AES-256-GCM encryption | Military-grade encryption for stored credentials |
| Environment-derived key | Encryption key is not stored in the database |
| No plaintext storage | Credentials exist in plaintext only during the encrypt/decrypt operation |
| No logging | Credential values are excluded from all logging |
| No API exposure | Credential values are never returned in API responses |
Comparison
| Aspect | OAuth 2.0 | API Key |
|---|---|---|
| User experience | Redirect to provider, grant access, return | Enter key in a form |
| Credential ownership | Provider issues tokens; Otesse never sees the user's password | User copies key from provider dashboard |
| Token rotation | Automatic via refresh tokens | Manual (user must generate new key and re-enter) |
| Scope control | Granular — request only needed permissions | Typically all-or-nothing based on key type |
| Revocation | Can revoke at the provider or in Otesse | Must revoke at the provider and update in Otesse |
| Complexity | Higher (multiple redirects, PKCE, state management) | Lower (single form submission) |
Credential Types
Each stored credential is classified by type:
| Type Code | Description | Used With |
|---|---|---|
oauthaccesstoken | Short-lived OAuth access token | OAuth providers |
oauthrefreshtoken | Long-lived token for refreshing access | OAuth providers |
api_key | Static API key | API key providers |
client_id | OAuth application client ID | OAuth providers |
client_secret | OAuth application client secret | OAuth providers |
webhook_secret | Signing secret for webhook verification | Webhook-enabled providers |
Which Providers Use Which Method
Currently, all seven connected providers in Otesse use API key authentication. OAuth support is built into the platform for future providers like Salesforce, Google Calendar, and QuickBooks that require delegated authorization flows.
The authentication method is configured at the provider level and cannot be changed by organizations or users. When you connect a provider, the system automatically presents the correct authentication flow based on the provider's configuration.
On this page