> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runalloy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Credentials

> Learn how to manage connector credentials in Connectivity API

# 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](/connectivity-api/users)
* 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:

```bash theme={null}
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:**

```json theme={null}
{
  "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:

```bash theme={null}
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:**

```json theme={null}
{
  "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:

```bash theme={null}
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:**

```json theme={null}
{
  "credentialId": "68d2e2fd5aa2c97c2ae99c24"
}
```

## Creating HTTP - Bearer Credentials

For connectors that use HTTP - Bearer tokens:

```bash theme={null}
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:**

```json theme={null}
{
  "credentialId": "68d2e2fd5aa2c97c2ae99c24"
}
```

## Creating HTTP - Basic Credentials

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

```bash theme={null}
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:**

```json theme={null}
{
  "credentialId": "68d2e2fd5aa2c97c2ae99c24"
}
```

> Note: For other required fields, it's best to confirm with the connector credential metadata. See [Discovering Credential Requirements](#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:

```bash theme={null}
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:

```json theme={null}
{
  "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](/connectivity-api/authentication) layers
* Explore [Executing Actions](/connectivity-api/quick-start#step-4%3A-execute-an-action) with credentials
* Review [Users](/connectivity-api/users) and credential ownership

## Need Help?

* [API Reference](/reference/connectivity-api/connectivity-api)
* [Support](mailto:support@runalloy.com)