Create, list, and delete the third-party connections (credentials) a user holds, and read credential metadata to know which auth fields to render for a given connector when building credentials manually or headlessly.
openapi: 3.0.3
info:
title: Alloy Automation Embedded & Unified API
description: >-
Alloy Automation is an embedded integration platform (iPaaS) and Unified API
for SaaS products. The Embedded product provisions end-user records, per-user
credentials/connections, and short-lived JWTs to render Alloy's embedded UI.
The Connectivity API discovers connectors, resources, and actions and executes
typed actions against a user's credential. The Passthrough API proxies raw
requests to a third-party provider using a stored credential. The Unified API
normalizes Commerce, CRM, and Accounting objects across many providers behind a
single interface. All endpoints use dated versioning (2024-03) and Bearer API
key authentication; per-user JWTs secure the embedded frontend.
version: '2024-03'
contact:
name: Alloy Automation Support
url: https://docs.runalloy.com
termsOfService: https://runalloy.com/terms/
servers:
- url: https://embedded.runalloy.com/2024-03
description: Embedded, Connectivity, Passthrough, and Unified API (2024-03)
security:
- bearerAuth: []
tags:
- name: Users
description: End-user records that scope credentials, integrations, and executions.
- name: User Tokens
description: Per-user JWTs for rendering the embedded frontend.
- name: Credentials
description: Third-party connections held by a user, plus credential metadata.
- name: Integrations
description: Available connectors and a user's enabled integrations.
- name: Connectivity
description: Discover resources/actions and execute typed actions.
- name: Passthrough
description: Raw proxied requests to a provider via a stored credential.
- name: Events
description: Execution events and observability.
- name: Unified Commerce
description: Normalized commerce objects (products, orders, customers).
- name: Unified CRM
description: Normalized CRM objects (contacts, companies, deals).
- name: Unified Accounting
description: Normalized accounting objects (accounts, invoices).
paths:
/users:
post:
operationId: createUser
tags: [Users]
summary: Create a user
description: Creates an end-user record in Alloy and returns its userId.
requestBody:
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/CreateUserRequest'
responses:
'200':
description: User created
content:
application/json:
schema:
$ref: '#/components/schemas/User'
get:
operationId: listUsers
tags: [Users]
summary: List users
description: Lists the end-user records in your Alloy account.
responses:
'200':
description: A list of users
content:
application/json:
schema:
type: object
properties:
users:
type: array
items:
$ref: '#/components/schemas/User'
/users/{userId}:
parameters:
- $ref: '#/components/parameters/UserId'
get:
operationId: getUser
tags: [Users]
summary: Retrieve a single user
responses:
'200':
description: The user
content:
application/json:
schema:
$ref: '#/components/schemas/User'
delete:
operationId: deleteUser
tags: [Users]
summary: Delete a user
responses:
'200':
description: User deleted
/users/{userId}/token:
parameters:
- $ref: '#/components/parameters/UserId'
post:
operationId: generateUserToken
tags: [User Tokens]
summary: Generate a new JWT for a user
description: >-
Generates a short-lived JSON Web Token (JWT) for the user, used to securely
render the Embedded Modal / Alloy Link in your frontend.
responses:
'200':
description: A user JWT
content:
application/json:
schema:
type: object
properties:
token:
type: string
description: Short-lived per-user JWT.
/users/{userId}/credentials:
parameters:
- $ref: '#/components/parameters/UserId'
get:
operationId: listUserCredentials
tags: [Credentials]
summary: List a user's credentials
responses:
'200':
description: The user's credentials
content:
application/json:
schema:
type: object
properties:
credentials:
type: array
items:
$ref: '#/components/schemas/Credential'
post:
operationId: createCredential
tags: [Credentials]
summary: Create a credential for a user
description: >-
Creates a credential (connection) for a user. Use the credential metadata
endpoint to learn which auth fields a connector requires.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCredentialRequest'
responses:
'200':
description: Credential created
content:
application/json:
schema:
$ref: '#/components/schemas/Credential'
/users/{userId}/credentials/{credentialId}:
parameters:
- $ref: '#/components/parameters/UserId'
- $ref: '#/components/parameters/CredentialId'
get:
operationId: getCredential
tags: [Credentials]
summary: Retrieve a credential
responses:
'200':
description: The credential
content:
application/json:
schema:
$ref: '#/components/schemas/Credential'
delete:
operationId: deleteCredential
tags: [Credentials]
summary: Delete a credential
responses:
'200':
description: Credential deleted
/metadata/credentials:
get:
operationId: getCredentialMetadata
tags: [Credentials]
summary: Retrieve credential structures
description: >-
Returns the basic structure of the data that must be provided when adding a
credential manually for an app, used before calling the create credential
endpoint.
parameters:
- name: app
in: query
required: false
schema:
type: string
description: Connector/app identifier to scope the credential metadata to.
responses:
'200':
description: Credential metadata
content:
application/json:
schema:
$ref: '#/components/schemas/CredentialMetadata'
/integrations:
get:
operationId: listIntegrations
tags: [Integrations]
summary: List integrations / connectors
description: >-
Lists the connectors available to power your integration marketplace, or the
integrations enabled for a specific user when userId is supplied.
parameters:
- name: userId
in: query
required: false
schema:
type: string
description: When present, scopes the list to a user's enabled integrations.
responses:
'200':
description: A list of integrations
content:
application/json:
schema:
type: object
properties:
integrations:
type: array
items:
$ref: '#/components/schemas/Integration'
/connectors/{connectorId}/resources:
parameters:
- name: connectorId
in: path
required: true
schema:
type: string
get:
operationId: listConnectorResources
tags: [Connectivity]
summary: List a connector's resources
description: Lists the entities (resources) a connector exposes.
responses:
'200':
description: Connector resources
content:
application/json:
schema:
type: object
properties:
resources:
type: array
items:
$ref: '#/components/schemas/Resource'
/connectors/{connectorId}/actions:
parameters:
- name: connectorId
in: path
required: true
schema:
type: string
get:
operationId: listConnectorActions
tags: [Connectivity]
summary: List a connector's actions
description: >-
Lists the actions an end-user can perform for a connector, optionally scoped
to a resource.
parameters:
- name: resource
in: query
required: false
schema:
type: string
responses:
'200':
description: Connector actions
content:
application/json:
schema:
type: object
properties:
actions:
type: array
items:
$ref: '#/components/schemas/Action'
/actions/execute:
post:
operationId: executeAction
tags: [Connectivity]
summary: Execute an action
description: >-
Executes a typed connector action against a user's credential and returns
the provider's response.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ExecuteActionRequest'
responses:
'200':
description: Action result
content:
application/json:
schema:
$ref: '#/components/schemas/ActionResult'
/passthrough:
post:
operationId: passthroughRequest
tags: [Passthrough]
summary: Make a passthrough request
description: >-
Makes a raw, authenticated request to a third-party API using a stored
credentialId. Alloy attaches the provider auth and refreshes tokens; you
supply the provider's native request path, method, headers, and body.
parameters:
- name: credentialId
in: query
required: true
schema:
type: string
description: The end-user credential ID to authenticate the request with.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PassthroughRequest'
responses:
'200':
description: The proxied provider response
content:
application/json:
schema:
type: object
additionalProperties: true
/events:
get:
operationId: listEvents
tags: [Events]
summary: List events
description: >-
Lists execution and provider events for observability. Supports pagination
via cursor.
parameters:
- name: userId
in: query
required: false
schema:
type: string
- $ref: '#/components/parameters/Cursor'
- $ref: '#/components/parameters/Limit'
responses:
'200':
description: A page of events
content:
application/json:
schema:
type: object
properties:
events:
type: array
items:
$ref: '#/components/schemas/Event'
pageInfo:
$ref: '#/components/schemas/PageInfo'
/events/{eventId}:
parameters:
- name: eventId
in: path
required: true
schema:
type: string
get:
operationId: getEvent
tags: [Events]
summary: Retrieve an event
responses:
'200':
description: The event
content:
application/json:
schema:
$ref: '#/components/schemas/Event'
/commerce/products:
get:
operationId: listProducts
tags: [Unified Commerce]
summary: List products
parameters:
- $ref: '#/components/parameters/ConnectionId'
- $ref: '#/components/parameters/Cursor'
- $ref: '#/components/parameters/Limit'
responses:
'200':
description: A page of products
content:
application/json:
schema:
type: object
properties:
products:
type: array
items:
$ref: '#/components/schemas/Product'
pageInfo:
$ref: '#/components/schemas/PageInfo'
/commerce/orders:
get:
operationId: listOrders
tags: [Unified Commerce]
summary: List orders
parameters:
- $ref: '#/components/parameters/ConnectionId'
- $ref: '#/components/parameters/Cursor'
- $ref: '#/components/parameters/Limit'
responses:
'200':
description: A page of orders
content:
application/json:
schema:
type: object
properties:
orders:
type: array
items:
$ref: '#/components/schemas/Order'
pageInfo:
$ref: '#/components/schemas/PageInfo'
/commerce/customers:
get:
operationId: listCommerceCustomers
tags: [Unified Commerce]
summary: List commerce customers
parameters:
- $ref: '#/components/parameters/ConnectionId'
- $ref: '#/components/parameters/Cursor'
- $ref: '#/components/parameters/Limit'
responses:
'200':
description: A page of commerce customers
content:
application/json:
schema:
type: object
properties:
customers:
type: array
items:
$ref: '#/components/schemas/CommerceCustomer'
pageInfo:
$ref: '#/components/schemas/PageInfo'
/crm/contacts:
get:
operationId: listContacts
tags: [Unified CRM]
summary: List contacts
parameters:
- $ref: '#/components/parameters/ConnectionId'
- $ref: '#/components/parameters/Cursor'
- $ref: '#/components/parameters/Limit'
responses:
'200':
description: A page of contacts
content:
application/json:
schema:
type: object
properties:
contacts:
type: array
items:
$ref: '#/components/schemas/Contact'
pageInfo:
$ref: '#/components/schemas/PageInfo'
post:
operationId: createContact
tags: [Unified CRM]
summary: Create a contact
parameters:
- $ref: '#/components/parameters/ConnectionId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Contact'
responses:
'200':
description: Contact created
content:
application/json:
schema:
$ref: '#/components/schemas/Contact'
/crm/companies:
get:
operationId: listCompanies
tags: [Unified CRM]
summary: List companies
parameters:
- $ref: '#/components/parameters/ConnectionId'
- $ref: '#/components/parameters/Cursor'
- $ref: '#/components/parameters/Limit'
responses:
'200':
description: A page of companies
content:
application/json:
schema:
type: object
properties:
companies:
type: array
items:
$ref: '#/components/schemas/Company'
pageInfo:
$ref: '#/components/schemas/PageInfo'
/crm/deals:
get:
operationId: listDeals
tags: [Unified CRM]
summary: List deals
parameters:
- $ref: '#/components/parameters/ConnectionId'
- $ref: '#/components/parameters/Cursor'
- $ref: '#/components/parameters/Limit'
responses:
'200':
description: A page of deals
content:
application/json:
schema:
type: object
properties:
deals:
type: array
items:
$ref: '#/components/schemas/Deal'
pageInfo:
$ref: '#/components/schemas/PageInfo'
/accounting/accounts:
get:
operationId: listAccounts
tags: [Unified Accounting]
summary: List accounts
description: Lists accounts from the connected ledger's chart of accounts.
parameters:
- $ref: '#/components/parameters/ConnectionId'
- $ref: '#/components/parameters/Cursor'
- $ref: '#/components/parameters/Limit'
responses:
'200':
description: A page of accounts
content:
application/json:
schema:
type: object
properties:
accounts:
type: array
items:
$ref: '#/components/schemas/Account'
pageInfo:
$ref: '#/components/schemas/PageInfo'
post:
operationId: createAccount
tags: [Unified Accounting]
summary: Create an account
parameters:
- $ref: '#/components/parameters/ConnectionId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Account'
responses:
'200':
description: Account created
content:
application/json:
schema:
$ref: '#/components/schemas/Account'
/accounting/invoices:
get:
operationId: listInvoices
tags: [Unified Accounting]
summary: List invoices
parameters:
- $ref: '#/components/parameters/ConnectionId'
- $ref: '#/components/parameters/Cursor'
- $ref: '#/components/parameters/Limit'
responses:
'200':
description: A page of invoices
content:
application/json:
schema:
type: object
properties:
invoices:
type: array
items:
$ref: '#/components/schemas/Invoice'
pageInfo:
$ref: '#/components/schemas/PageInfo'
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >-
Bearer API key in the Authorization header, e.g.
`Authorization: Bearer YOUR_API_KEY`. Frontend calls use a per-user JWT
instead of the master key.
parameters:
UserId:
name: userId
in: path
required: true
schema:
type: string
description: The Alloy end-user record ID.
CredentialId:
name: credentialId
in: path
required: true
schema:
type: string
description: The end-user credential (connection) ID.
ConnectionId:
name: connectionId
in: query
required: true
schema:
type: string
description: The connected account (credential) to read/write unified data through.
Cursor:
name: cursor
in: query
required: false
schema:
type: string
description: Opaque pagination cursor from a prior pageInfo.
Limit:
name: limit
in: query
required: false
schema:
type: integer
default: 50
maximum: 250
description: Maximum number of records to return per page.
schemas:
CreateUserRequest:
type: object
properties:
username:
type: string
description: Optional external username / label for the user.
fullName:
type: string
User:
type: object
properties:
userId:
type: string
username:
type: string
fullName:
type: string
createdAt:
type: string
format: date-time
CreateCredentialRequest:
type: object
required: [app]
properties:
app:
type: string
description: Connector/app identifier the credential is for.
data:
type: object
additionalProperties: true
description: Auth field values, shaped per the credential metadata.
Credential:
type: object
properties:
credentialId:
type: string
app:
type: string
userId:
type: string
createdAt:
type: string
format: date-time
CredentialMetadata:
type: object
properties:
app:
type: string
fields:
type: array
items:
type: object
properties:
name:
type: string
label:
type: string
type:
type: string
required:
type: boolean
Integration:
type: object
properties:
connectorId:
type: string
name:
type: string
category:
type: string
authType:
type: string
enum: [oauth2, apiKey, basic]
Resource:
type: object
properties:
name:
type: string
label:
type: string
Action:
type: object
properties:
name:
type: string
label:
type: string
resource:
type: string
parameters:
type: array
items:
type: object
additionalProperties: true
ExecuteActionRequest:
type: object
required: [credentialId, action]
properties:
credentialId:
type: string
connectorId:
type: string
action:
type: string
input:
type: object
additionalProperties: true
ActionResult:
type: object
properties:
status:
type: string
data:
type: object
additionalProperties: true
PassthroughRequest:
type: object
required: [method, path]
properties:
method:
type: string
enum: [GET, POST, PUT, PATCH, DELETE]
path:
type: string
description: The provider-native request path, e.g. /admin/api/2024-01/orders.json
headers:
type: object
additionalProperties:
type: string
body:
type: object
additionalProperties: true
Event:
type: object
properties:
eventId:
type: string
userId:
type: string
type:
type: string
status:
type: string
createdAt:
type: string
format: date-time
data:
type: object
additionalProperties: true
Product:
type: object
properties:
id:
type: string
title:
type: string
sku:
type: string
price:
type: number
currency:
type: string
remoteId:
type: string
Order:
type: object
properties:
id:
type: string
orderNumber:
type: string
totalPrice:
type: number
currency:
type: string
status:
type: string
customerId:
type: string
remoteId:
type: string
CommerceCustomer:
type: object
properties:
id:
type: string
email:
type: string
firstName:
type: string
lastName:
type: string
remoteId:
type: string
Contact:
type: object
properties:
id:
type: string
firstName:
type: string
lastName:
type: string
email:
type: string
phone:
type: string
companyId:
type: string
remoteId:
type: string
Company:
type: object
properties:
id:
type: string
name:
type: string
domain:
type: string
remoteId:
type: string
Deal:
type: object
properties:
id:
type: string
name:
type: string
amount:
type: number
currency:
type: string
stage:
type: string
companyId:
type: string
remoteId:
type: string
Account:
type: object
properties:
id:
type: string
name:
type: string
type:
type: string
classification:
type: string
currency:
type: string
remoteId:
type: string
Invoice:
type: object
properties:
id:
type: string
number:
type: string
contactId:
type: string
totalAmount:
type: number
currency:
type: string
status:
type: string
issueDate:
type: string
format: date
dueDate:
type: string
format: date
remoteId:
type: string
PageInfo:
type: object
properties:
hasNextPage:
type: boolean
nextCursor:
type: string