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: Loop Returns, Trello, ShipStation, and others

HTTP Bearer

Some platforms use HTTP bearer tokens. Example platforms: Shippo and others

HTTP Basic Auth

Some platforms use HTTP basic authentication with username and password. Example platforms: Freshdesk, Jira, Mailgun, 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",
      "authConfigRequired": false,
      "inputSchema": {
        "type": "object",
        "properties": {
          "userId": {
            "type": "string",
            "description": "User ID of the credential"
          },
          "authenticationType": {
            "type": "string",
            "description": "Type of authentication method of the connector",
            "const": "oauth2"
          },
          "redirectUri": {
            "type": "string",
            "format": "uri",
            "description": "Redirect URI for OAuth authentication"
          }
        },
        "required": ["userId", "authenticationType", "redirectUri"]
      },
      "sampleInput": {
        "userId": "68fe36549000cce448466858",
        "authenticationType": "oauth2",
        "redirectUri": "https://example.com"
      }
    }
  ]
}

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

Redirect the user to the oauthUrl
User logs into the third-party platform (e.g., HubSpot)
User grants permissions to your application
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/connectors/shipStation/credentials \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "x-api-version: {API_VERSION}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "userId": "{USER_ID}",
    "authenticationType": "apiKey",
    "data": {
      "apiKey": "user_provided_api_key",
    }
  }'

Response:

{
  "credentialId": "68d2e2fd5aa2c97c2ae99c24"
}

Creating HTTP - Bearer Credentials

For connectors that use HTTP - Bearer tokens:

curl -X POST https://production.runalloy.com/users/connectors/shippo/credentials \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "x-api-version: {API_VERSION}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "userId": "{USER_ID}",
    "authenticationType": "http",
    "data": {
      "accessToken": "user_provided_access_token",
    }
  }'

Response:

{
  "credentialId": "68d2e2fd5aa2c97c2ae99c24"
}

Creating HTTP - Basic Credentials

For connectors that use HTTP - Basic authentication. Others may require other information like domain like Jira for example.

curl -X POST https://production.runalloy.com/users/connectors/jira/credentials \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "x-api-version: {API_VERSION}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "userId": "{USER_ID}",
    "authenticationType": "http",
    "data": {
      "domain": "your_jira_domain",
      "username": "user_provided_username",
      "password": "user_provided_password"
    }
  }'

Response:

{
  "credentialId": "68d2e2fd5aa2c97c2ae99c24"
}

Note: For other required fields, it’s best to confirm with the connector credential metadata. See Discovering Credential Requirements. We have provided a sample input for the connector’s credential metadata.

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

Learn about Authentication layers
Explore Executing Actions with credentials
Review Users and credential ownership

Getting Started

Credentials

Credentials

Understanding Credentials

What Credentials Store

Credential Ownership

Authentication Types

OAuth 2.0

API Keys

HTTP Bearer

HTTP Basic Auth

Discovering Credential Requirements

Creating OAuth 2.0 Credentials

Step 1: Initiate OAuth Flow

Step 2: User Authenticates

Step 3: Token Exchange

Step 4: Save Credential ID

Creating API Key Credentials

Creating HTTP - Bearer Credentials

Creating HTTP - Basic Credentials

Using Credentials

Automatic Token Refresh

Credential Lifecycle

When Credentials Become Invalid

Handling Invalid Credentials

Security

What You Store

What Alloy Automation Stores

Important Security Note

Testing with Sandbox Accounts

Next Steps

Need Help?

Getting Started

​Credentials

​Understanding Credentials

​What Credentials Store

​Credential Ownership

​Authentication Types

​OAuth 2.0

​API Keys

​HTTP Bearer

​HTTP Basic Auth

​Discovering Credential Requirements

​Creating OAuth 2.0 Credentials

​Step 1: Initiate OAuth Flow

​Step 2: User Authenticates

​Step 3: Token Exchange

​Step 4: Save Credential ID

​Creating API Key Credentials

​Creating HTTP - Bearer Credentials

​Creating HTTP - Basic Credentials

​Using Credentials

​Automatic Token Refresh

​Credential Lifecycle

​When Credentials Become Invalid

​Handling Invalid Credentials

​Security

​What You Store

​What Alloy Automation Stores

​Important Security Note

​Testing with Sandbox Accounts

​Next Steps

​Need Help?

Credentials

Understanding Credentials

What Credentials Store

Credential Ownership

Authentication Types

OAuth 2.0

API Keys

HTTP Bearer

HTTP Basic Auth

Discovering Credential Requirements

Creating OAuth 2.0 Credentials

Step 1: Initiate OAuth Flow

Step 2: User Authenticates

Step 3: Token Exchange

Step 4: Save Credential ID

Creating API Key Credentials

Creating HTTP - Bearer Credentials

Creating HTTP - Basic Credentials

Using Credentials

Automatic Token Refresh

Credential Lifecycle

When Credentials Become Invalid

Handling Invalid Credentials

Security

What You Store

What Alloy Automation Stores

Important Security Note

Testing with Sandbox Accounts

Next Steps

Need Help?