Using OAuth 2.0 Clients In Flow

Overview

Flow OAuth Client Authentication allows you to create secure OAuth 2.0 credentials that can be used to authenticate API requests to your Chain.io flows. This feature is ideal for:

• Issuing credentials to third-party trading partners
• Authenticating automated systems and integrations
• Providing secure, token-based access to your flows
• Managing multiple API clients with individual credentials

OAuth clients use the industry-standard OAuth 2.0 Client Credentials flow, where a Client ID and Client Secret are exchanged for a short-lived JWT (JSON Web Token) that can be used to authenticate flow submissions.

Creating an OAuth Client

Step 1: Navigate to OAuth Clients

1. Go to Workspace Settings in your Chain.io portal
2. Select Flow OAuth Clients from the
3. Click the Create New Client button

Step 2: Configure Client Details

You will need to provide three pieces of information:

Client Name (Required)

• A human-readable description of the client
• Example: "Partner ABC Production API" or "Internal ERP System"
• This helps you identify the purpose of each client

Client ID (Required)

• Always starts with your company's 4-character short code (automatically prefixed)
• Followed by a hyphen -
• Then 5-10 alphanumeric characters of your choice
• Example: If your company code is abcd, your Client ID might be abcd-PRODAPI
• Note: The company prefix cannot be changed

Activation Email Address (Required)

• Email address where the activation link will be sent
• Can be your own email or a third-party recipient's email
• The recipient will receive the Client Secret directly upon activation
• This ensures the secret goes directly to the person who will use it
• Tip: If you are creating one for your own use, you can use your own email address

Step 3: Create the Client

1. Click Create to generate the OAuth client
2. The client will be created in Pending Activation status
3. An activation email will be sent to the specified address
4. The recipient has 24 hours to activate the client before the link expires

Activating an OAuth Client

Activation Process

1. Check the email inbox for the activation email
2. Click the Activate Client link in the email
3. You will be taken to the Chain.io activation page
   • No Chain.io account is required to activate a client
4. Review the Client ID displayed on the page
5. Click the Activate Client button

Retrieving Your Credentials

Once activated, you will see:

• Client ID - Copy this using the copy button
• Client Secret - Copy this using the copy button

⚠️ IMPORTANT: This is the ONLY time you will be able to view the Client Secret.

• Make sure to copy and store both the Client ID and Client Secret securely
• If you lose the Client Secret, you will need to create a new OAuth client
• The activation page provides instructions on how to use these credentials

Security Best Practices

• Store credentials in a secure password manager or secrets vault
• Never commit credentials to source control or share them in plain text
• Do not expose the Client Secret in client-side code or public repositories
• If you suspect credentials have been compromised, immediately revoke the client and create a new one

Using OAuth Clients in Your Flows

Configuring a Flow to Accept OAuth Authentication

1. Navigate to your trading partner or create a new integration
2. Create a new flow or edit an existing one
3. When configuring your Source Connection, select API as the connection type
4. In the Authentication section, you will now see OAuth Client as an option
5. Select OAuth Client from the authentication dropdown
6. Choose the OAuth client you created from the dropdown list
7. Complete the rest of your flow configuration as normal (destination, mappings, etc.)
8. Save and Deploy your flow

Once deployed, the flow will only accept requests authenticated with a valid JWT token obtained using the selected OAuth client credentials.

Exchanging Credentials for a JWT Token

Before you can submit data to your OAuth-protected flow, you must exchange your Client ID and Client Secret for a JWT access token.

Token Exchange Endpoint

POST https://webhooks.chain.io/oauth/token

Request Format

Headers:

Content-Type: application/x-www-form-urlencoded

Body Parameters:

grant_type=client_credentials
client_id=YOUR_CLIENT_ID
client_secret=YOUR_CLIENT_SECRET

Example: cURL

curl -X POST https://webhooks.chain.io/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=abcd-PRODAPI" \
  -d "client_secret=your-client-secret-here"

Example: Postman

1. Create a new POST request to https://webhooks.chain.io/oauth/token
2. Set the body type to x-www-form-urlencoded
3. Add three key-value pairs:
   • grant_type: client_credentials
   • client_id: Your Client ID
   • client_secret: Your Client Secret
4. Send the request

Response

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 900
}

Response Fields:

• access_token - The JWT token to use for authentication
• token_type - Always "Bearer"
• expires_in - Token lifetime in seconds (15 minutes / 900 seconds)

⚠️ Note: JWT tokens expire after 15 minutes. Request a new token when needed.

Submitting Data to Your Flow

Once you have obtained a JWT token, you can use it to submit data to your OAuth-protected flow.

Request Format

Method: POST (or as configured in your flow)

URL: Your flow's webhook URL

Headers:

Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json (or other types depending on file format)

Body: Your JSON payload (as defined by your flow)

Example: cURL

curl -X POST https://webhooks.chain.io/YOUR_FLOW_ENDPOINT \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "your": "data",
    "goes": "here"
  }'

Example: Postman

1. Create a new POST request to your flow's endpoint URL
2. Go to the Authorization tab
   • Type: Bearer Token
   • Token: Paste your JWT access token
3. Go to the Body tab
   • Select raw and JSON
   • Enter your JSON payload
4. Send the request

Success Response

If authentication and submission are successful, you will receive a response from your flow (typically a 200 status code). You can view the flow execution in your Chain.io portal under the trading partner's flow execution history.

Managing OAuth Clients

Viewing Active Clients

1. Navigate to Workspace Settings → Flow OAuth Clients
2. You will see a list of all OAuth clients with their status:
   • Active - Client has been activated and can be used
   • Pending Activation - Client created but not yet activated
   • Revoked - Client has been disabled

Revoking a Client

If you need to disable an OAuth client:

1. Go to Workspace Settings → Flow OAuth Clients
2. Find the client you want to revoke
3. Click the Revoke button
4. Confirm the revocation

⚠️ Note: Revoked clients cannot be reactivated. Any flows configured to use a revoked client will reject authentication attempts. You will need to create a new client if needed and redploy the flows.

Activation Expiration

• Activation links expire 24 hours after creation
• If the link expires before activation, you will need to create a new OAuth client
• There is no way to resend an expired activation link

Rotating Client Secrets

If you need to change your Client Secret without creating a new client (e.g., for security compliance or after potential credential exposure), you can rotate the secret using the API.

Important: This is an advanced operation. The old secret will be immediately invalidated upon successful rotation.

Rotation Endpoint

POST https://webhooks.chain.io/oauth/rotate-secret

Request Format

Headers:

Content-Type: application/x-www-form-urlencoded

Body Parameters:

client_id=YOUR_CLIENT_ID
client_secret=YOUR_CURRENT_CLIENT_SECRET

Example: cURL

curl -X POST https://webhooks.chain.io/oauth/rotate-secret \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=abcd-PRODAPI" \
  -d "client_secret=your-current-secret-here"

Example: Postman

1. Create a new POST request to https://webhooks.chain.io/oauth/rotate-secret
2. Set the body type to x-www-form-urlencoded
3. Add two key-value pairs:
   • client_id: Your Client ID
   • client_secret: Your current Client Secret
4. Send the request

Response

{
  "client_secret": "7ab69c78-9abf-48e6-a16e-ae528abdbb548e79609559274bce97467facd508b66d"
}

Response Fields:

• client_secret - Your new Client Secret

⚠️ CRITICAL: The old secret is immediately invalidated when you rotate.

Best Practices for Secret Rotation

Before Rotation:

1. Plan the rotation during a maintenance window if possible
2. Notify any teams or partners using the client
3. Have a rollback plan in case of issues

During Rotation:

1. Call the rotation endpoint and securely store the new secret
2. Update all systems using the old secret with the new secret
3. Test authentication with the new secret before fully deploying

After Rotation:

1. Verify all systems are using the new secret successfully
2. Monitor for any authentication failures
3. Update your documentation and password manager with the new secret

When to Rotate:

• Security compliance requirements (e.g., every 90 days)
• Suspected credential compromise or exposure
• Offboarding a team member who had access to the secret
• After a security audit or penetration test
• As part of regular security hygiene

Important Notes:

• The rotation is instantaneous - there is no grace period where both secrets work
• Any in-flight JWT tokens obtained with the old secret remain valid until they expire (15 minutes)
• If rotation fails, your current secret remains valid
• You must have the current valid secret to perform rotation (you cannot rotate if you've lost the secret)

Common Use Cases

Scenario 1: Issuing Credentials to a Trading Partner

1. Create an OAuth client with the partner's name in the Client Name field
2. Use the partner's email address as the Activation Email
3. The partner receives the activation email directly
4. They activate and receive the credentials
5. They use the credentials to authenticate their system's API calls to your flow

Benefits: The secret never passes through your organization's email, increasing security.

Scenario 2: Authenticating Your Own Internal System

1. Create an OAuth client for your system (e.g., "ERP Production")
2. Use your own email address
3. Activate and retrieve the credentials
4. Store the credentials in your application's secure configuration
5. Implement token exchange logic in your application code
6. Use the JWT to authenticate flow submissions

Scenario 3: Multiple Environments

Create separate OAuth clients for different environments:

• abcd-DEV for development
• abcd-TEST for testing
• abcd-PROD for production

This allows you to track usage separately and revoke environment-specific credentials if needed.

Troubleshooting

"Invalid activation link" Error

Cause: The activation link has expired (> 24 hours) or has already been used.

Solution: Create a new OAuth client.

"Client already activated" Error

Cause: You are trying to activate a client that has already been activated.

Solution: The client is ready to use. If you lost the credentials, you must create a new client.

"Invalid client credentials" Error (Token Exchange)

Cause: The Client ID or Client Secret is incorrect.

Solution:

• Verify you copied the credentials correctly
• Ensure there are no extra spaces or characters
• If you lost the secret, create a new OAuth client

"Token expired" Error (Flow Submission)

Cause: The JWT token has expired (> 15 minutes old).

Solution: Request a new JWT token from the token exchange endpoint.

"Unauthorized" Error (Flow Submission)

Possible Causes:

1. JWT token is invalid or expired
2. The flow is not configured to accept the OAuth client you're using
3. The OAuth client has been revoked

Solution:

1. Request a fresh JWT token
2. Verify the flow's source connection is configured to use your OAuth client
3. Check that the client is still active in Workspace Settings

Flow Not Receiving Data

Checklist:

1. Verify the flow is deployed (not in draft state)
2. Confirm you're using the correct flow endpoint URL
3. Ensure the Authorization header is properly formatted: Bearer YOUR_TOKEN
4. Check that your JSON payload matches the flow's expected input format
5. Review the flow execution history for error details

Secret Rotation Failed

Cause: Invalid credentials provided to the rotation endpoint or client has been revoked.

Solution:

1. Verify you're using the correct current Client ID and Secret
2. Ensure the client is still active (not revoked) in Workspace Settings
3. Check for typos or extra spaces in your credentials
4. If you've lost the current secret, you cannot rotate - create a new OAuth client instead

Authentication Works But Suddenly Stops

Cause: The Client Secret may have been rotated by someone else.

Solution:

1. Contact your team to see if anyone rotated the secret
2. If rotation occurred, obtain the new secret and update your configuration
3. If the client was revoked, create a new client

Security Considerations

Token Lifetime

• JWT tokens expire after 15 minutes for security
• Implement token refresh logic in your application
• Request a new token before the current one expires

Credential Storage

• DO NOT hardcode credentials in your application code
• Use environment variables or secure configuration management
• Consider using a secrets manager (e.g., AWS Secrets Manager, Azure Key Vault, HashiCorp Vault)

Access Control

• Create separate OAuth clients for different partners or systems
• Revoke clients immediately if credentials are compromised
• Regularly audit active OAuth clients and revoke unused ones
• Implement a secret rotation policy (e.g., rotate every 90 days for compliance)
• Use the rotation endpoint to update secrets without creating new clients

Monitoring

• Monitor flow execution logs for unusual activity
• Track failed authentication attempts
• Set up alerts for suspicious patterns

API Reference Summary

Token Exchange Endpoint

Endpoint: POST https://webhooks.chain.io/oauth/token

Request Body (x-www-form-urlencoded):

Success Response (200):

{
  "access_token": "string",
  "token_type": "Bearer",
  "expires_in": 900
}

Error Responses:

• 400 - Invalid request (missing parameters)
• 401 - Invalid client credentials
• 500 - Server error

Secret Rotation Endpoint

Endpoint: POST https://webhooks.chain.io/oauth/rotate-secret

Request Body (x-www-form-urlencoded):

Success Response (200):

{
  "client_secret": "string"
}

Error Responses:

• 400 - Invalid request (missing parameters)
• 401 - Invalid client credentials
• 404 - Client not found or already revoked
• 500 - Server error

⚠️ Note: Old secret is immediately invalidated upon successful rotation.

Flow Submission

Endpoint: POST https://webhooks.chain.io/{your-flow-endpoint}

Headers:

Body: JSON payload as defined by your flow configuration

Additional Resources

• OAuth 2.0 Specification: https://oauth.net/2/
• JWT Documentation: https://jwt.io