Akoya Apps Management API 2.0.0
Paste the following code into your favorite text editor and save it as a YAML file.
Documentation
Paste the following code into your favorite text editor and save it as a YAML file.
openapi: 3.1.0
x-stoplight:
id: dcn0m6nzpaelf
info:
title: Akoya Apps Management API v2.0.0
description: |-
Updated 4/15/2026
The Akoya Apps Management API helps you create and update your applications on the Akoya network.
Apps Management API updates:
- v2.0
April 28, 2025
- Updated response schema with the "logo" and "icon" properties.
February 20, 2025
- Made minor corrections regarding how to reset client secret.
- Set `status` query param to "optional."
- January 15, 2025
- Added clarifications regarding the use of the `products` query param.
- October 4, 2024
- Create App endpoint: Specify that the scope must include at least one product in addition to Account Information.
- Get Subscriptions for App endpoint: Mention that if an app is created with only Account Information, no subscriptions will be returned for that app.
- API updated to support DCR standards.
- v1.3.1
- Updated description for the Akoya providers by product endpoint:
- Corrected query examples.
- v1.3
- `put-subscriptions` now supports adding products to subscriptions. When products are added, the app must send end-users back through authorization to consent to the added product.
- `get-subscriptions-appId` is updated with a new response to support ability to add products (above).
- `get-apps` now returns Akoya products used by apps.
- The service token now requires the scope parameter to indicate the Akoya service used (Management API).
- Additional special characters added to `name` in app creation. `#$&'()*+,-./|–é`
- v1.2
- When searching providers for supported Akoya products, you're now able to indicate if you'd like providers who match ALL of your requested products or ANY (some).
- v1.1
- You may now GET a list of your apps and their details.
contact:
name: Akoya Support
url: 'https://www.akoya.com'
email: support@akoya.com
license:
name: Apache License Version 2.0
url: 'https://www.apache.org/licenses/LICENSE-2.0'
version: 2.0.0
servers:
- url: https://sandbox-api.akoya.com
description: Sandbox API server
- url: https://api.akoya.com
description: Production API server
components:
securitySchemes:
basicAuth:
type: http
scheme: basic
bearerAuth:
type: http
scheme: bearer
security:
- bearerAuth: []
paths:
'/manage/{version}/apps/register':
post:
tags:
- Apps
summary: Create App
description: |-
Creates an application. This endpoint will automatically subscribe the created app to all valid providers.
>
> ⚠️ `scope` must include at least one product in addition to Account Information.
>
- `client_name` should be alphanumeric and may include special characters: `#$&'()\*+,-./|-é.`. `client_name` needs to be unique. You cannot create two applications with the same `client_name`.
- `logo_uri` must be a URL to a file (Required).
- Minimum height: 200px
- Minimum width: 200px
- Maximum height: 1080px
- Maximum width: 1080px
- File types: transparent PNG or JPG
- Maximum file size: 2 MB
- `icon_uri` must be a URL to a file (Optional).
- Must be square.
- Height = width.
- Minimum height: 40px
- Minimum width: 40px
- Maximum height: 200px
- Maximum width: 200px
- File types: transparent PNG or JPG
- Maximum file size: 2 MB
- `scope`: Products this app will use. This product list needs to be provided as a string where the products are space-seperated. You should include at least one product in addition to Account Information.
operationId: post-register
requestBody:
content:
application/json:
schema:
type: object
examples:
Request body:
value:
client_name: app_name
description: this is app description
redirect_uris:
- 'https://example.com/callback'
logo_uri: 'https://dummyimage.com/240x240/000/ffffff.png'
icon_url: 'https://dummyimage.com/240x240/000/ffffff.png'
contacts:
- test@example.com
client_uri: 'http://localhost:8888'
scope: account_info payments
responses:
'200':
description: OK
headers:
Content-Type:
schema:
type: string
example: application/json; charset=utf-8
X-Akoya-Interaction-Id:
schema:
type: string
example: Root=1-66981abd-3baf2692467140e0aeffcb57d6997db9
content:
application/json:
schema:
type: object
properties:
client_id:
type: string
client_secret:
type: string
client_name:
type: string
redirect_uris:
type: array
items:
type: string
client_uri:
type: string
contacts:
type: array
items:
type: string
description:
type: string
logo_uri:
type: string
icon_url:
type: string
scope:
type: string
grant_types:
type: array
items:
type: string
status:
type: string
examples:
Successful response:
value:
client_id: client_id
client_secret: client_secret
client_name: app_name
redirect_uris:
- 'https://akoya.com'
client_uri: 'https://akoya.com'
contacts:
- test@gmail.com
description: this is app description
logo_uri: 'https://dummyimage.com/240x240/000/ffffff.png'
icon_url: 'https://dummyimage.com/240x240/000/ffffff.png'
scope: account_info payments
grant_types:
- authorization_code
- refresh_token
status: Approved
'400':
description: Invalid Argument
headers:
Content-Type:
schema:
type: string
example: application/json; charset=utf-8
X-Akoya-Interaction-Id:
schema:
type: string
example: Root=1-66981a23-be7c421caa3d4727a2a4033e437d3f9c
content:
application/json:
schema:
type: object
properties:
code:
type: string
message:
type: string
examples:
Invalid Argument:
value:
code: InvalidArgument
message: unable to validate image
'409':
description: Already Exists
headers:
Content-Type:
schema:
type: string
example: application/json; charset=utf-8
X-Akoya-Interaction-Id:
schema:
type: string
example: Root=1-66988d4a-737ddfea0a324298955ee24ad635d24e
content:
application/json:
schema:
type: object
properties:
code:
type: string
message:
type: string
examples:
App already exists:
value:
code: AlreadyExists
message: This app name already exists for this recipientId.
x-stoplight:
id: y74qbaw8wn7ug
parameters:
- schema:
type: string
name: version
in: path
required: true
description: Management API major version (e.g. v2)
'/manage/{version}/recipients/{recipientId}/apps/{appId}':
patch:
tags:
- Apps
summary: Update App
description: |-
Update your application. The request format follows the JSON Patch specification ([<u>RFC 6902</u>](https://datatracker.ietf.org/doc/html/rfc6902/)<u>).</u>
- Only the add, replace, and remove (for lists only) operations are supported.
- `client_name` and the Akoya products your app uses (scope) cannot be updated with this endpoint.
- You cannot change an application's name after it's created.
requestBody:
content:
application/json:
schema:
type: array
items:
type: object
properties:
op:
type: string
path:
type: string
value:
type: string
examples:
Replace description:
value:
- op: replace
path: /description
value: this is a modified description
Replace description and add redirect URI:
value:
- op: replace
path: /description
value: this is a modified description
- op: add
path: /redirect_uris/1
value: 'https://random2.com'
Reset client secret:
value:
- op: replace
path: /client_secret
value: ''
Add a new redirect URI:
value:
- op: add
path: /redirect_uris/0
value: 'https://example.com/callback'
description: "The request body will vary depending on what attributes of your application you're looking to update or replace.\r\n\r\n`\"op\"` (operation) accepted values: \r\n- `\"add\"`\r\n- `\"replace\"`\r\n - Use the `\"replace\"` operation when resetting your client secret.\r\n- `\"remove\"`\r\n\r\n`\"path\"` (app attribute) accepted values:\r\n- `\"/description\"` (app description)\r\n- `\"/redirect_uris/{number}`\" `{number}` is the redirect URI you want to alter (e.g. the first, the second). The redirect URI order is as shown in the Data Recipient Hub. Example: `\"/redirect_uris/1\"` refers to the second listed redirect URI.\r\n- `\"/client_secret\"`To reset, send an empty value. The new secret will return in the response. \r\n- `\"/client_uri\"`\r\n- `\"/contacts\"`\r\n- `\"/logo_uri\"`\r\n- `\"/icon_url\"`\r\n\r\n\r\n`\"value\"` (the value of the updated attribute) accepted values:\r\n- `\"\"` (blank string - resetting client secret ONLY)\r\n- Free text for other operation\r\n\r\n**Note**: You can enter more than one operation in the same request.\r\n"
operationId: patch-app
parameters:
- name: recipientId
in: path
description: Your recipient id. You may find your recipientId in the Data Recipient Hub under Team Management/Company Id.
schema:
type: string
required: true
example: '{{recipient_id}}'
- name: appId
in: path
description: The ID of your application
schema:
type: string
required: true
example: '{{appId}}'
responses:
'200':
description: OK
headers:
Content-Type:
schema:
type: string
example: application/json; charset=utf-8
X-Akoya-Interaction-Id:
schema:
type: string
example: Root=1-669845bf-9095f59723be485783308ffc7f6f7be7
content:
application/json:
schema:
type: object
properties:
client_id:
type: string
client_name:
type: string
owner:
type: string
redirect_uris:
type: array
items:
type: string
client_uri:
type: string
contacts:
type: array
items:
type: string
description:
type: string
logo_uri:
type: string
scope:
type: array
items:
type: string
examples:
Replaced description:
summary: 200 OK
value:
client_id: c8a14d90-7843-4b4f-995f-e081ac99fa96
client_name: app_name_2
owner: paprika_rec
redirect_uris:
- 'https://example.com/callback'
client_uri: 'http://localhost:8888'
contacts:
- test@example.com
description: this is a modified description
logo_uri: 'https://dummyimage.com/240x240/000/ffffff.png'
scope:
- account_info
- payments
Added redirect URI and replaced description:
summary: 200 OK - Add a new Redirect URI
value:
client_id: c8a14d90-7843-4b4f-995f-e081ac99fa96
client_name: app_name_2
owner: paprika_rec
redirect_uris:
- 'https://example.com/callback1'
- 'https://example.com/callback2'
client_uri: 'http://localhost:8888'
contacts:
- test@example.com
description: this is a modified description
logo_uri: 'https://dummyimage.com/240x240/000/ffffff.png'
scope:
- account_info
- balances
'400':
description: Invalid Argument
headers:
Content-Type:
schema:
type: string
example: application/json; charset=utf-8
X-Akoya-Interaction-Id:
schema:
type: string
example: Root=1-6698469c-c1817b040ae2492f85de1078cec6e974
content:
application/json:
schema:
type: array
items:
type: object
properties:
code:
type: string
message:
type: string
examples:
Invalid Argument:
value:
- code: InvalidArgument
message: /client_name may not be modified
x-stoplight:
id: 30q256eb9paot
parameters:
- schema:
type: string
name: recipientId
in: path
required: true
description: Recipient ID
- schema:
type: string
name: appId
in: path
required: true
description: The ID of your application
- schema:
type: string
name: version
in: path
required: true
description: Management API major version (e.g. v2)
'/manage/{version}/recipients/{recipientId}/apps':
get:
tags:
- Apps
summary: Get All Apps
operationId: get-apps
description: |-
Get a paginated list of all your applications.
You can use the `next` and the `prev` links to page through the response. You can also pass a `offset` and a `limit` parameter to get a specific page. The default page size is 50, and the maximum allowed page size is 500.
parameters:
- name: offset
in: query
schema:
type: integer
example: 10
description: Number of skipped items (default = 0)
- name: limit
in: query
schema:
type: integer
example: 2
description: 'Number of items per page (default = 50, must be <=500)'
- name: recipientId
in: path
schema:
type: string
required: true
example: '{{recipient_id}}'
description: Your recipient id. You may find your recipientId in the Data Recipient Hub under Team Management/Company Id.
responses:
'200':
description: OK
headers:
Content-Type:
schema:
type: string
example: application/json; charset=utf-8
X-Akoya-Interaction-Id:
schema:
type: string
example: Root=1-669826f3-3c87279718484dfaaac99a81938d5a8f
content:
application/json:
schema:
type: object
properties:
page:
type: object
properties:
total_elements:
type: integer
links:
type: object
properties:
next:
type: object
properties:
href:
type: string
prev:
type: object
properties:
href:
type: string
apps:
type: array
items:
type: object
properties:
client_id:
type: string
client_name:
type: string
description:
type: string
redirect_uris:
type: array
items:
type: string
client_uri:
type: string
logo_uri:
type: string
contacts:
type: array
items:
type: string
scope:
type: string
owner:
type: string
examples:
Successful response:
value:
page:
total_elements: 221
links:
next:
href: /manage/v2/recipients/paprika_rec/apps?limit=2&offset=12
prev:
href: /manage/v2/recipients/paprika_rec/apps?limit=2&offset=8
apps:
- client_id: a24fd6b6-fa38-482e-9c91-26ca4bc1a490
client_name: paprika_testNew_4
description: this is app description
redirect_uris:
- 'https://example.com/callback1'
client_uri: 'http://localhost:8888'
logo_uri: 'https://picsum.photos/1024/1024.jpg'
contacts:
- test@example.com
scope: balances account_info payments investments customers
owner: paprika_rec
- client_id: dbc84f1b-e6f1-4d09-a928-16411a7f87ea
client_name: paprika_testNew_5
description: this is app description
redirect_uris:
- 'https://example.com/callback2'
client_uri: 'http://localhost:8888'
logo_uri: 'https://picsum.photos/1024/1024.jpg'
contacts:
- test@example.com
scope: payments investments customers balances account_info
owner: paprika_rec
x-stoplight:
id: tw402dgdozgxe
parameters:
- schema:
type: string
name: version
in: path
required: true
description: Management API major version (e.g. v2)
- schema:
type: string
name: recipientId
in: path
required: true
description: Your recipient id. You may find your recipientId in the Data Recipient Hub under Team Management/Company Id.
'/manage/{version}/recipients/{recipientId}/products':
get:
tags:
- Products
summary: Get Purchased Products
operationId: get-products
description: Get a list of all your purchased Akoya products.
security:
- bearerAuth: []
parameters:
- name: recipientId
in: path
schema:
type: string
required: true
example: '{{recipient_id}}'
description: Your recipient id. You may find your recipientId in the Data Recipient Hub under Team Management/Company Id.
responses:
'200':
description: OK
headers:
Content-Type:
schema:
type: string
example: application/json; charset=utf-8
X-Akoya-Interaction-Id:
schema:
type: string
example: Root=1-669752ce-eb6114c500be450a917eb1f9326df3bd
content:
application/json:
schema:
type: object
properties:
products:
type: array
items:
type: object
properties:
name:
type: string
display_name:
type: string
description:
type: string
required:
type: boolean
examples:
Successful response:
value:
products:
- name: account_info
display_name: Account Info
description: 'Account display name, masked account number, type, description.'
required: true
- name: payments
display_name: Payments
description: Identifiers necessary to make ACH and RTP payments.
required: false
- name: investments
display_name: Accounts & Investments
description: Detailed information on underlying holdings and positions of investment accounts.
required: false
- name: customers
display_name: Customers
description: 'Verified contact information on file, including name, email, address, and phone number.'
required: false
- name: balances
display_name: Balances
description: 'Balances and rates of bank accounts, credit cards, loans, investments, and more.'
required: false
- name: transactions
display_name: Transactions
description: 'Up to two years of transaction data across account types, including amounts, dates, and descriptions.'
required: false
'401':
description: Unauthorized
headers:
Content-Type:
schema:
type: string
example: application/json
content:
application/json:
schema:
type: object
properties:
code:
type: integer
message:
type: string
examples:
Unauthorized:
value:
code: 602
message: Customer not authorized
x-stoplight:
id: qzmx42ywtn87b
parameters:
- schema:
type: string
name: version
in: path
required: true
description: Management API major version (e.g. v2)
- schema:
type: string
name: recipientId
in: path
required: true
description: Your recipient id. You may find your recipientId in the Data Recipient Hub under Team Management/Company Id.
'/manage/{version}/recipients/{recipientId}/providers':
get:
tags:
- Providers
summary: Get Valid Providers For Products
operationId: get-providers
description: ">\n> \U0001F4D8 While you can only specify one product in the \"Try it now\" component below, this endpoint allows you to use `&` to separate two or more products. The format should be `products=val1&products=val2&products=val3`. \n> \n> The result will be a list of providers that support ALL the products listed.\n\nGet a paginated list of all providers connected to Akoya that support any of the products passed in as a query parameter (`products`).\n\n>\n> \U0001F4D8 For optimal performance, call this endpoint once and cache the logo and icon URLs for future use rather than requesting them each time you display your account selector.\n\nThe payload now includes the following fields:\n- `provider_id` - `providerId`\n- `display_name` - The provider's display name\n- `logo` - The provider's full logo\n- `icon` - The provider's icon (often a submark logo)\n- `provider_url` - The provider's website\n\n\nYou can use the `next` and the `prev` links to page through the response. You can also pass a `offset` and a `limit` parameter to get a specific page. The default page size is 50, and the maximum allowed page size is 500."
parameters:
- name: products
in: query
schema:
type: string
example: balances
required: true
description: Akoya product (e.g. balances).
- name: recipientId
in: path
schema:
type: string
required: true
example: '{{recipient_id}}'
description: Your recipient id. You may find your recipientId in the Data Recipient Hub under Team Management/Company Id.
responses:
'200':
description: OK
headers:
Content-Type:
schema:
type: string
example: application/json; charset=utf-8
X-Akoya-Interaction-Id:
schema:
type: string
example: Root=1-66975c0f-f0c01004a1d943b09e5752aeeeee115c
content:
application/json:
schema:
type: object
properties:
providers:
type: array
items:
type: object
properties:
provider_id:
type: string
display_name:
type: string
logo:
type: string
icon:
type: string
provider_url:
type: string
examples:
Successful Response:
value:
providers:
- provider_id: 'test:12345'
display_name: Test Bank
logo: 'https://cdn.dev.ddp.akoya.com/assets/providers/test:12345/logo.jpeg'
icon: 'https://cdn.dev.ddp.akoya.com/assets/providers/test:12345/icon.png'
provider_url: 'https://www.testbank.com'
- provider_id: 'test:67890'
display_name: Sample Credit Union
logo: 'https://cdn.dev.ddp.akoya.com/assets/providers/test:4567/logo.jpeg'
icon: 'https://cdn.dev.ddp.akoya.com/assets/providers/test:4567/icon.png'
provider_url: 'https://www.samplecreditunion.com'
x-stoplight:
id: 1h4aglyjy3fhv
parameters:
- schema:
type: string
name: version
in: path
required: true
description: Management API major version (e.g. v2)
- schema:
type: string
name: recipientId
in: path
required: true
description: Your recipient id. You may find your recipientId in the Data Recipient Hub under Team Management/Company Id.
'/manage/{version}/subscriptions/{appId}':
get:
tags:
- Subscriptions
summary: Get Subscriptions For App
description: |-
Get a paginated list of all ACTIVE subscriptions for this application.
>
> ⚠️ If you created an app with only the Account Information product, no subscriptions will be returned for that app.
>
You can use the `next` and the `prev` links to page through the response. You can also pass a `offset` and a `limit` parameter to get a specific page. The default page size is 50, and the maximum allowed page size is 500.
operationId: get-subscriptions
parameters:
- name: offset
in: query
schema:
type: integer
example: 1
description: Number of skipped items (default = 0)
- name: limit
in: query
schema:
type: integer
example: 2
description: 'Number of items per page (default = 50, must be <=500)'
- name: appId
in: path
schema:
type: string
required: true
example: '{{appId}}'
description: The ID of your application
responses:
'200':
description: OK
headers:
Content-Type:
schema:
type: string
example: application/json; charset=utf-8
X-Akoya-Interaction-Id:
schema:
type: string
example: Root=1-66984b62-050b7264672b4131bc7086d78b89657d
content:
application/json:
schema:
type: object
properties:
page:
type: object
properties:
total_elements:
type: integer
links:
type: object
properties:
next:
type: object
properties:
href:
type: string
prev:
type: object
properties:
href:
type: string
subscriptions:
type: array
items:
type: object
properties:
provider_id:
type: string
display_name:
type: string
subscription_status:
type: string
account_categories:
type: array
items:
type: string
products:
type: array
items:
type: string
examples:
Successful response:
value:
page:
total_elements: 1618
links:
next:
href: /manage/v2/subscriptions/c8a14d90-7843-4b4f-995f-e081ac99fa96?limit=2&offset=3
prev:
href: /manage/v2/subscriptions/c8a14d90-7843-4b4f-995f-e081ac99fa96?limit=2&offset=0
subscriptions:
- provider_id: mikomo
display_name: Mikomo
subscription_status: ACTIVE
account_categories:
- loanAccount
- locAccount
- investmentAccount
- depositAccount
products:
- account_info
- balances
- customer
- provider_id: mainst
display_name: Main St. Bank
subscription_status: ACTIVE
account_categories:
- depositAccount
- locAccount
- loanAccount
products:
- account_info
- balances
- customers
x-stoplight:
id: brxvslxjrjtjk
parameters:
- schema:
type: string
name: version
in: path
required: true
description: Management API major version (e.g. v2)
- schema:
type: string
name: appId
in: path
required: true
description: The id of your application
'/manage/{version}/subscriptions/{appId}/status':
get:
tags:
- Subscriptions
summary: Get Subscriptions For App - Filter By Status
description: |-
Get a paginated list of all subscriptions filtered by the `status` query parameter for this application.
Valid values for the `status` parameter are:
- `ACTIVE`
- `PENDING`
- `PROCESSING`
- `TERMINATED`
- `DENIED`
Omitting the `status` parameter will return ALL subscriptions across all statuses.
You can use the `next` and the `prev` links to page through the response. You can also pass a `offset` and a `limit` parameter to get a specific page. The default page size is 50 and the maximum allowed page size is 500.
operationId: get-subscriptions-filter
parameters:
- name: status
in: query
schema:
type: string
enum:
- ACTIVE
- PENDING
- PROCESSING
- TERMINATED
- DENIED
example: ACTIVE
description: Your subscription status
- name: offset
in: query
schema:
type: integer
example: 1
description: Number of skipped items (default = 0)
- name: limit
in: query
schema:
type: integer
example: 2
description: 'Number of items per page (default = 50, must be <=500)'
- name: appId
in: path
schema:
type: string
required: true
example: '{{appId}}'
description: The ID of your application
responses:
'200':
description: OK
headers:
Content-Type:
schema:
type: string
example: application/json; charset=utf-8
X-Akoya-Interaction-Id:
schema:
type: string
example: Root=1-66987978-577180bc1dee4dfcbca4a0297e860832
content:
application/json:
schema:
type: object
properties:
page:
type: object
properties:
total_elements:
type: integer
links:
type: object
properties:
next:
type: object
properties:
href:
type: string
prev:
type: object
properties:
href:
type: string
subscription_status:
type: array
items:
type: object
properties:
provider_id:
type: string
display_name:
type: string
status:
type: string
products:
type: array
items:
type: string
examples:
Successful response example 1:
summary: 200 OK
value:
page:
total_elements: 1620
links:
next:
href: /manage/v2/subscriptions/c8a14d90-7843-4b4f-995f-e081ac99fa96/status?limit=2&offset=3&status=ACTIVE
prev:
href: /manage/v2/subscriptions/c8a14d90-7843-4b4f-995f-e081ac99fa96/status?limit=2&offset=0&status=ACTIVE
subscription_status:
- provider_id: mikomo
display_name: Mikomo Financial
status: ACTIVE
products:
- balances
- provider_id: mainst
display_name: Main St. Bank
status: ACTIVE
products:
- balances
Successful response example 2:
summary: 200 OK - Get PENDING Subscriptions
value:
page:
total_elements: 15
links:
next:
href: /manage/v2/subscriptions/c8a14d90-7843-4b4f-995f-e081ac99fa96/status?limit=2&offset=6&status=PENDING
prev:
href: /manage/v2/subscriptions/c8a14d90-7843-4b4f-995f-e081ac99fa96/status?limit=2&offset=2&status=PENDING
subscription_status:
- provider_id: mikomo
display_name: Mikomo Financial
status: PENDING
products:
- balances
- provider_id: mainst
display_name: Main St. Bank
status: PENDING
products:
- balances
x-stoplight:
id: ivluaxrc0px6j
parameters:
- schema:
type: string
name: version
in: path
required: true
description: Management API major version (e.g. v2)
- schema:
type: string
name: appId
in: path
required: true
description: The id of your application
x-internal: true
tags:
- name: Apps
- name: Products
- name: Providers
- name: Subscriptions