Skip to main content

​
Credentials

Credentials are authentication tokens or API keys that Alloy Automation uses to communicate with third-party platforms on behalf of your users. Each credential is attached to a specific user and connector.

​
Understanding Credentials

​
What Credentials Store

Credentials contain the authentication data required to access third-party platforms:
  • OAuth 2.0 tokens: Access tokens and refresh tokens for platforms like HubSpot, Salesforce, and Notion
  • API keys: Static API keys and secrets for platforms like QuickBooks and Zendesk
  • Custom authentication: Other authentication schemes as required by specific connectors

​
Credential Ownership

  • Each credential belongs to a specific user
  • A user can have multiple credentials for different connectors
  • A user can have multiple credentials for the same connector (e.g., multiple HubSpot accounts)
  • Alloy Automation stores and manages credentials securely with encryption at rest

​
Authentication Types

​
OAuth 2.0

Most modern SaaS platforms use OAuth 2.0. Alloy Automation handles the complete OAuth flow including automatic token refresh. Example platforms: HubSpot, Xero, Notion, and others

​
API Keys

Some platforms use API keys or custom authentication schemes. Example platforms: Zendesk, NetSuite and others

​
Discovering Credential Requirements

Before creating credentials, discover what authentication data a connector requires: 
curl --request GET \
  --url https://production.runalloy.com/connectors/{connectorId}/credentials/metadata \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'x-api-version: {API_VERSION}'
Response: 
{
    "metadata": [
        {
            "authenticationType": "oauth2",
            "inputSchema": {
                "type": "object",
                "properties": {
                    "userId": {
                        "type": "string"
                    },
                    "redirectUri": {
                        "type": "string"
                    },
                    "data": {
                        "type": "object",
                        "properties": {},
                        "required": []
                    }
                },
                "required": [
                    "userId",
                    "redirectUri"
                ]
            },
            "authConfigRequired": false
        }
    ]
}
Use the response to:
  • Determine the authentication type (OAuth 2.0, API key, etc.)
  • Identify required fields for credential creation
  • Build dynamic credential collection forms
  • Validate input before creating credentials

​
Creating OAuth 2.0 Credentials

​
Step 1: Initiate OAuth Flow

In our example above, we know Hubspot uses OAuth. Therefore, we’ll pass oauth2 as the authenticationType to the POST /credentials endpoint to request an authorization URL: 
curl -X POST https://production.runalloy.com/connectors/hubspot/credentials \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "x-api-version: {API_VERSION}" \
  -H "Authorization: Bearer YOUR_API_KEY}" \
  -d '{
    "connectorId": "hubspot",
    "userId": "{USER_ID}",
    "authenticationType": "oauth2",
    "redirectUri": "https://your-app.com/oauth/callback"
  }'
Response: 
{
    "oauthUrl": "https://api.runalloy.com/api/strategy/connector/hubspot/authorize?userId=62a{USER_ID}&redirectUri=https%3A%2F%2Fyour-app.com%2Foauth%2Fcallback&token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7Il9pZCI6IjYyYTIzMWUwZWM3Y2Q2MDAxNGIyNmQ0NiJ9LCJpYXQiOjE3NjA3MzY2NDAsImV4cCI6MTc2MDc0MDI0MH0.LPF45F_HhKM8a4cucycidIILOfYgnqKWbFUxFM4CBn0"
}

​
Step 2: User Authenticates

  1. Redirect the user to the oauthUrl
  2. User logs into the third-party platform (e.g., HubSpot)
  3. User grants permissions to your application
  4. Platform redirects back to your redirectUri with an authorization code

​
Step 3: Token Exchange

Alloy Automation automatically exchanges the authorization code for access and refresh tokens. The credential is created and attached to the user without additional API calls.

​
Step 4: Save Credential ID

After the OAuth flow completes, you’ll receive a credentialId. Store this ID in your database mapped to the user.

​
Creating API Key Credentials

In the example above, we looked at how to create credentials for apps using OAuth. For connectors that use API keys: 
curl -X POST https://production.runalloy.com/users/{USER_ID}/credentials \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "x-api-version: {API_VERSION}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "connectorId": "quickbooks",
    "credentialType": "apiKey",
    "data": {
      "apiKey": "user_provided_api_key",
      "apiSecret": "user_provided_secret"
    }
  }'
Response: 
{
  "credentialId": "68d2e2fd5aa2c97c2ae99c24"
}

​
Using Credentials

Once created, reference the credential when executing actions: 
curl -X POST https://production.runalloy.com/connectors/hubspot/actions/createContact/execute \
  -H "Content-Type: application/json" \
  -H "x-api-version: {API_VERSION}" \
  -H "x-alloy-userid: {USER_ID}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "credentialId": "{CREDENTIAL_ID}",
    "requestBody": {
      "firstName": "Test",
      "lastName": "Engineer",
      "email": "test.engineer@sap.com"
    }
  }'

​
Automatic Token Refresh

For OAuth 2.0 credentials, Alloy Automation automatically refreshes access tokens when they expire. You don’t need to handle token refresh logic in your application.

​
Credential Lifecycle

​
When Credentials Become Invalid

Credentials can become invalid when:
  • User revokes access in the third-party platform
  • OAuth tokens are manually revoked
  • API keys are rotated or deleted in the third-party platform

​
Handling Invalid Credentials

When a credential is invalid, the API returns an error: 
{
  "error": {
    "source": "CONNECTIVITY_API",
    "code": "INVALID_CREDENTIAL",
    "message": "Credential not found or has been revoked",
    "details": {
      "credentialId": "{CREDENTIAL_ID}"
    }
  }
}
Solution: Prompt the user to reconnect their integration by initiating a new OAuth flow or providing updated API keys.

​
Security

​
What You Store

You are responsible for securely storing:
  • Mapping between your users and Alloy Automation userId values
  • Mapping between users and their credentialId values

​
What Alloy Automation Stores

Alloy Automation securely stores:
  • OAuth access and refresh tokens (encrypted at rest)
  • API keys and secrets (encrypted at rest)
  • Credential metadata (connector type, creation date, etc.)

​
Important Security Note

Credential IDs (credentialId) are safe to store in your database, but they are only usable with your API key. Always validate that a user owns a credential before allowing operations with that credential.

​
Testing with Sandbox Accounts

When testing credential flows, use sandbox or developer accounts:
  • HubSpot: Free developer account
  • Salesforce: Developer sandbox
  • Notion: Personal workspace
This prevents test data from affecting production systems.

​
Next Steps

​
Need Help?

⌘I