# API platform

The API platform APIs allow users to programmatically create and manage API platform assets like endpoints, collections, clients, and access profiles.

# Quick reference

Type Resource Description
GET /api_collections List API collections.
POST /api_collections Create API collection.
GET /api_endpoints List API endpoints in a collection.
PUT /api_endpoints/:api_endpoint_id/enable Enable an API endpoint in a collection.
PUT /api_endpoints/:api_endpoint_id/disable Disable an API endpoint in a collection.
GET /api_clients List API clients.
POST /api_clients Create API client.
GET /api_access_profiles List access profiles belonging to an API client.
POST /api_access_profiles Create an access profile belonging to an API client.
PUT /api_access_profiles Update an access profile belonging to an API client.
PUT /api/api_access_profiles/:api_access_profile_id/enable Enable an access profile belonging to an API client.
PUT /api/api_access_profiles/:api_access_profile_id/disable Disable an access profile belonging to an API client.
PUT /api_access_profiles/:access_profile_id/refresh_secret Refreshes access profile token or secret.

# List API collections

List all API collections.

GET /api/api_collections

# URL parameters

Name Type Description
per_page integer Number of API collections to return in a single page. Defaults to 100. Max is 100.
page integer Page number of the API collections to fetch. Defaults to 1.

# Response

[
    {
        "id": 1361,
        "name": "Quote to cash",
        "version": "1.0",
        "url": "https://api.peatql.io/quote-to-cash-v1",
        "api_spec_url": "https://www.workato.com/doc/service/quote-to-cash-v1/swagger?token=4cab5bdf2cebbe2b4ahjkc9ac175f60c",
        "created_at": "2020-06-15T22:20:15.327-07:00",
        "updated_at": "2020-06-15T22:20:15.327-07:00"
    }
]

# Create API collection

Create an API collection.

POST /api/api_collections

# Payload

Name Type Description
name string
required
Name of the collection

# Sample request

curl  -X POST https://www.workato.com/api/api_collections \
      -H 'x-user-email: <email>' \
      -H 'x-user-token: <token>' \
      -H 'Content-Type: application/json' \
      -d '{
            "name": "Netsuite customers"
          }'

# Response

{
    "id": 1391,
    "name": "Netsuite customers",
    "version": "1.0",
    "url": "https://api.na.workato.com/abstergoi/netsuite-customers-v1",
    "api_spec_url": "https://www.workato.com/doc/service/netsuite-customers-v1/swagger?token=774513f8a712djkls90s7f5a3165eb96d",
    "created_at": "2020-07-31T08:24:31.439-07:00",
    "updated_at": "2020-07-31T08:24:31.439-07:00"
}

# List API endpoints

Lists all API endpoints. Specify the api_collection_id to obtain the list of endpoints in a specific collection.

GET /api/api_endpoints

# URL parameters

Name Type Description
api_collection_id string ID of the API collection. If the parameter is not provided, all API endpoints are returned.
per_page integer Number of API endpoints to return in a single page. Defaults to 100. Max is 100.
page integer Page number of the API endpoints to fetch. Defaults to 1.

# Sample request

curl  -X GET 'https://www.workato.com/api/api_endpoints?api_collection_id=1391' \
      -H 'x-user-email: <email>' \
      -H 'x-user-token: <token>' \
      -H 'Content-Type: application/json' \

# Response

[
  {
      "id": 9903,
      "api_collection_id": 1391,
      "flow_id": 39999,
      "name": "salesforce search",
      "method": "GET",
      "url": "https://api.na.workato.com/abstergoi/netsuite-customers-v1/salesforce/search",
      "legacy_url": null,
      "base_path": "/abstergoi/netsuite-customers-v1/salesforce/search",
      "path": "salesforce/search",
      "active": false,
      "legacy": false,
      "created_at": "2020-08-05T05:59:55.991-07:00",
      "updated_at": "2020-08-05T05:59:55.991-07:00"
  }
]

# Enable API endpoint

Enables an API endpoint. The underlying recipe must be started to enable the API endpoint successfully.

PUT /api/api_endpoints/:api_endpoint_id/enable

# URL parameters

Name Type Description
api_endpoint_id string
ID of the API endpoint.

# Sample request

curl  -X PUT https://www.workato.com/api/api_endpoints/1213/enable \
      -H 'x-user-email: <email>' \
      -H 'x-user-token: <token>' \
      -H 'Content-Type: application/json' \

# Disable API endpoint

Disables an active API endpoint. The endpoint can no longer be called by a client.

PUT /api/api_endpoints/:api_endpoint_id/disable

# URL parameters

Name Type Description
api_endpoint_id string
ID of the API endpoint.

# Sample request

curl  -X PUT https://www.workato.com/api/api_endpoints/1213/disable \
      -H 'x-user-email: <email>' \
      -H 'x-user-token: <token>' \
      -H 'Content-Type: application/json' \

# List API clients

List all API clients.

GET /api/api_clients

# Response

[
  {
      "id": 1255,
      "name": "Automation Inc.",
      "created_at": "2020-07-31T03:44:22.435-07:00",
      "updated_at": "2020-07-31T03:44:22.435-07:00"
  },
  {
      "id": 1890,
      "name": "Umbrella Corporation",
      "created_at": "2020-07-31T03:44:22.435-07:00",
      "updated_at": "2020-07-31T03:44:22.435-07:00"
  }
]

# Create API client

Create a new API client.

POST /api/api_clients

# Payload

Name Type Description
name string
required
Name of the client

# Sample request

curl  -X POST https://www.workato.com/api/api_clients \
      -H 'x-user-email: <email>' \
      -H 'x-user-token: <token>' \
      -H 'Content-Type: application/json' \
      -d '{
            "name": "Automation Inc.",
          }'

# Response

{
    "id": 1255,
    "name": "Automation Inc.",
    "created_at": "2020-07-31T03:44:22.435-07:00",
    "updated_at": "2020-07-31T03:44:22.435-07:00"
}

# List access profiles

List all access profiles belonging to an API client.

GET /api/api_access_profiles

# URL parameters

Name Type Description
api_client_id string
required
API client id
per_page integer Number of access profile to return in a single page. Defaults to 100. Max is 100.
page integer Page number of the access profile to fetch. Defaults to 1.

# Sample request

curl  -X GET 'https://www.workato.com/api/api_access_profiles?api_client_id=1255' \
      -H 'x-user-email: <email>' \
      -H 'x-user-token: <token>'

# Response

[
  {
      "id": 4676,
      "exteranl_id": "A298247",
      "name": "Customer A",
      "notification_email": "customer-a@a.com",
      "plan_id": "business_yearly",
      "in_trial": false,
      "created_at": "2019-07-11T10:08:41.693-07:00",
      "updated_at": "2019-07-11T10:22:35.132-07:00"
  }
]

# Create access profile

Create an access profile belonging to an API client. To use this endpoint, the account must contain at least 1 API collection to assign to the access profile.

The response returned depends on the auth type chosen (Auth token, JSON web token or OAuth 2.0).

  • Auth token authorization will return the auth token in the secret response
  • JWT token has 2 signing methods: HMAC and RSA. Depending on the chosen method, the respective secret or public is required in the payload
  • OAuth 2.0 authorization will return the client ID and secret in oauth_client_id and oauth_client secret
POST /api/api_access_profiles

# URL parameters

Name Type Description
api_client_id string
ID of the API client.

# Payload

Name Type Description
name string
required
Name of the access profile
api_collection_ids string
required
IDs of collections to add to the access profile
active boolean
required
Whether the access profile is disabled or enabled. A client with a disabled access profile cannot call any APIs.
auth_type string
required
Authentication method to validate requests. Available types are: token, jwt, oauth2 and oidc.
jwt_method string The JWT signing method. If the auth_type is jwt, this is required. Available methods are hmac and rsa for HMAC and RSA respectively.
jwt_secret string Based on the method, specify the HMAC shared secret or the RSA public key.
oidc_issuer Discovery URL of identity provider or OIDC service. Provide only one of this or oidc_jwks_uri, not both.
Only application if auth_type is jwt or oidc.
oidc_jwks_uri JWKS URL of identity provider or OIDC service. Provide only one of this or oidc_issuer, not both.
Only application if auth_type is jwt or oidc.
access_profile_claim If you wish to use a custom claim to identify this access profile, provide the JWT claim key here. Learn more
Only application if auth_type is jwt or oidc.
required_claims Provide a list of claims that you wish to enforce.Only application if auth_type is jwt or oidc.
allowed_issuers Provide a list of issuers (iss value in JWT claims) that you wish to allow. Leave If iss claim is enforced in required_claims, leave this blank to require any iss value. Only application if auth_type is jwt or oidc.

# Sample request (Auth token)

curl  -X POST 'https://www.workato.com/api/api_access_profiles?api_client_id=1255'\
      -H 'x-user-email: <email>' \
      -H 'x-user-token: <token>'
      -d '{
  	          "name": "Sales team",
  	          "api_collection_ids": [1391, 1388],
              "auth_type": "token",
  	          "active": true
           }'

# Sample request (JWT HMAC)

curl  -X POST https://www.workato.com/api/api_access_profiles?api_client_id=1255\
      -H 'x-user-email: <email>' \
      -H 'x-user-token: <token>'
      -d '{
	           "name": "HMAC API",
	           "api_collection_ids": [1391, 1388],
	           "auth_type": "jwt",
	           "jwt_method": "rsa",
	           "jwt_secret": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA4ngjihh5hXDRe0c1qPNc\nrF7RIoAG/iNZXruTspeX8e2auMBXTwVI0sLgwUo26lMXCRAvC004JWKugzh1UHXY\nsjmtwZFRznqhb/ojJDi785+zbmVNLWmbIB/ChBUyckBSExsmR0nOpQhiW0przr2J\ncQIDAQAB\n-----END PUBLIC KEY-----",
	           "active": true
           }'

# Response (Auth token)

{
    "id": 26985,
    "name": "New test",
    "api_client_id": 1255,
    "api_collection_ids": [
        1395
    ],
    "active": true,
    "auth_type": "token",
    "jwt_method": null,
    "jwt_secret": null,
    "oauth_client_id": null,
    "oauth_client_secret": null,
    "secret": "e3a1ce1d46c4hjk8kfj26781c6ed3073312451ee0990035bf8a4bc90c2a2",
    "created_at": "2020-08-12T08:03:05.492-07:00",
    "updated_at": "2020-08-12T08:03:05.492-07:00"
}

# Update access profile

Update an access profile belonging to an API client.

The response returned depends on the auth type chosen (Auth token, JSON web token or OAuth 2.0).

  • Auth token authorization will return the auth token in the secret response
  • JWT token has 2 signing methods: HMAC and RSA. Depending on the chosen method, the respective secret or public is required in the payload
  • OAuth 2.0 authorization will return the client ID and secret in oauth_client_id and oauth_client secret
PUT /api/api_access_profiles/:api_access_profile_id

# Path parameters

Name Type Description
api_access_profile_id string
required
API access profile ID.

# Query parameters

Name Type Description
api_client_id string
required
API client ID.

# Payload

Name Type Description
name string
required
Name of the access profile
api_collection_ids string
required
IDs of collections to add to the access profile
active boolean
required
Whether the access profile is disabled or enabled. A client with a disabled access profile cannot call any APIs.
auth_type string
required
Authentication method to validate requests. Available types are: token, jwt, oauth2 and oidc.
jwt_method string The JWT signing method. If the auth_type is jwt, this is required. Available methods are hmac and rsa for HMAC and RSA respectively.
jwt_secret string Based on the method, specify the HMAC shared secret or the RSA public key.
oidc_issuer Discovery URL of identity provider or OIDC service. Provide only one of this or oidc_jwks_uri, not both.
Only application if auth_type is jwt or oidc.
oidc_jwks_uri JWKS URL of identity provider or OIDC service. Provide only one of this or oidc_issuer, not both.
Only application if auth_type is jwt or oidc.
access_profile_claim If you wish to use a custom claim to identify this access profile, provide the JWT claim key here. Learn more
Only application if auth_type is jwt or oidc.
required_claims Provide a list of claims that you wish to enforce.Only application if auth_type is jwt or oidc.
allowed_issuers Provide a list of issuers (iss value in JWT claims) that you wish to allow. Leave If iss claim is enforced in required_claims, leave this blank to require any iss value. Only application if auth_type is jwt or oidc.

# Sample request (Auth token)

curl  -X PUT 'https://www.workato.com/api/api_access_profiles/27894?api_client_id=1255'\
      -H 'x-user-email: <email>' \
      -H 'x-user-token: <token>'
      -d '{
  	          "name": "Sales team",
  	          "api_collection_ids": [1391, 1388],
              "auth_type": "token",
  	          "active": true
           }'

# Enable access profile

Enable an access profile belonging to an API client. Enabling an access profile will allow API calls to be accepted with the enabled profile.

This call returns success or error messages for Unauthorized/Bad requests.

PUT /api/api_access_profiles/:api_access_profile_id/enable

# URL parameters

Name Type Description
api_access_profile_id string
required
ID of the access profile.

# Sample request (Auth token)

curl  -X PUT https://www.workato.com/api/api_access_profiles/1213/enable \
      -H 'x-user-email: <email>' \
      -H 'x-user-token: <token>' \
      -H 'Content-Type: application/json' \

# Disable access profile

Disable an access profile belonging to an API client. Disabling an access profile will stop allowing API calls to be accepted with the access profile.

This call returns success or error messages for Unauthorized/Bad requests.

PUT /api/api_access_profiles/:api_access_profile_id/disable

# URL parameters

Name Type Description
api_access_profile_id string
required
ID of the access profile.

# Sample request (Auth token)

curl  -X PUT https://www.workato.com/api/api_access_profiles/1213/disable \
      -H 'x-user-email: <email>' \
      -H 'x-user-token: <token>' \
      -H 'Content-Type: application/json' \

# Refresh token/secret

Refreshes the auth token or OAuth 2.0 client secret. This endpoint will fail if the authorization type on the access profile is JWT.

The response returned depends on the authorization type of the access profile (Auth token or OAuth 2.0).

  • Auth token authorization will return a new auth token in the secret response
  • OAuth 2.0 authorization will return a new client ID and secret in oauth_client_id and oauth_client secret
PUT /api/api_access_profiles/:access_profile_id/refresh_secret

# URL parameters

Name Type Description
access_profile_id string
required
API access profile ID

# Response (Auth token)

{
    "id": 26962,
    "name": "Sales team",
    "api_client_id": 1255,
    "api_collection_ids": [
        1391
    ],
    "active": true,
    "auth_type": "token",
    "jwt_method": null,
    "jwt_secret": null,
    "oauth_client_id": null,
    "oauth_client_secret": null,
    "secret": "xxxxxxxxxxx",
    "created_at": "2020-07-31T09:10:03.310-07:00",
    "updated_at": "2020-08-05T06:08:46.290-07:00"
}