openapi: 3.0.0
servers:
- url: 'https://api.devbank.apiture.com/apiKeys'
info:
title: API Keys
description: >
API Keys provide [secure access](https://developer.apiture.com/docs/secure-access/) to Apiture APIs. Each client application requires a unique API
key to access the APIs in each runtime API environment (such as `api.canapi.bank`, `api.devbank.apiture.com`, or `api.3rdparty.bank`).
The API Key resource managed by this API creates the following:
* The API Key which is passed in the `API-Key` request header of
each API call;
* A unique Client ID and Client Secret (also known as _client credentials_)
with which the client application
can authenticate with the authentication endpoints in the service.
Each key resource requires a _client application_ and a target runtime _api environment_ when constructing the API key. These resources are passed
in the `createKey` operation via links in the request body via the [link relations](http://developer.apiture.com/docs/concepts/links/):
* `apiture:clientApplication`
* `apiture:environment`
The client application may be associated with a partner organization (business).
Each key may be in one of several states (`pending`, `active`, `inactive`); Keys are initially created in the `pending` state. State transitions
are performed by a `POST` via the `activateKey`, `deactivateKey` operations using the links in the key resource:
* `apiture:activate`
* `apiture:deactivate`
which must be initially performed by a administrator with permission to approve keys. Users may deactivate/reactivate keys after they have been
approved. Deactivating a key is also called _revoking_ a key.
When a client application is deactivated, all its associated keys and client credentials are deactivated.
When a client application is activated, all its associated keys and client credentials are activated.
When a client application is deleted, all its associated keys and client credentials are deleted.
There are five types of keys
* The Discoverer Key (`discoverer`) is for unauthenticated users to explore
the Apiture APIs in a limited manner, using a sample
user ("John Smith") identity. The Discoverer Key
is shared by all unauthenticated users.
It is recycled on a periodic basis:
a new Discoverer key is minted each day to replace the old one,
and the old one is then revoked, marked as expired, and deleted at some time
after that.
* An Explorer key (`explorer`) is for authenticated users to explore
the Apiture APIs in more depth. It is provisioned after
a user registers (moderated by the portal admin).
Using this, the developer can also create sample
data that only they can access (bank accounts, etc.).
The user can view their Explorer key via their
My Account page on the developer portal.
* Partner keys (`partner`) are associated with a specific
client partner organization (company), a
registered client application, and
a specific runtime environment (such
as a dev, test, or other environment.
* Production keys (`production`) are partner keys that are attached
to a production (non-test, non-development) environment.
* Private keys (`private`) are for Apiture use only.
This API provides convenient operations for creating or accessing Discoverer and Explorer keys.
# Error Types
Error responses in this API may have one of the `type` values described below.
See [Errors](https://developer.apiture.com/docs/concepts/errors) for more information
on error responses and error types.
invalidPartnerDomain
**Description**: The current user's email address is associated with a restricted partner organization domain.
**Remediation**: Register using a company email address, not an email service.
keyRefNotFound
**Description**: The key parameter was malformed or does not refer to an existing or accessible key.
**Remediation**: Pass a valid key in the key query parameter.
passwordRequired
**Description**: When updating the discoverer key credentials, the `sampleUserPassword` property is required if the request incldues the
`sampleUserName`.
**Remediation**: Pass `sampleUserPassword` if the request incldues the `sampleUserName`.
version: 0.26.0
contact:
name: Apiture
url: 'https://developer.apiture.com'
email: api@apiture.com
termsOfService: 'https://developer.apiture.com/docs/Apiture-Open-API-License-Agreement.pdf'
tags:
- name: Key
description: Keys for secure API access.
- name: Key States
description: Change the state of API keys.
- name: Discoverer Key
description: Access to Discoverer Keys
- name: Explorer Key
description: Access to Explorer Keys
- name: API
description: Endpoints which describe this API.
paths:
/activeKeys:
post:
operationId: activateKey
security:
- apiKey: []
accessToken:
- data/write
summary: Activate a key
description: >-
Attempt to activate a key.
For non-administrators, this submits a request to the portal administrators to approve or reject the request.
This may also change the state to `pending`. The corresponding response code is 200.
For administrator users, this action changes the
state directly (if the state can be changed to `active` or is already `active`). The API key is also deployed into the target environment. The
corresponding response code is 200.
This operation is available via the `apiture:activate` link on the key resource, if and only if the
key is eligible for the activate operation. The response is the updated representation of the key.
tags:
- Key States
parameters:
- $ref: '#/components/parameters/keyQueryParam'
- $ref: '#/components/parameters/noNotificationQueryParam'
responses:
'200':
description: OK. The operation succeeded.
content:
application/hal+json:
schema:
$ref: '#/components/schemas/key'
application/json:
schema:
$ref: '#/components/schemas/key'
'202':
description: Accepted. The request to activate a key has been accepted. The state may change to `pending` while the request is processed.
content:
application/hal+json:
schema:
$ref: '#/components/schemas/key'
application/json:
schema:
$ref: '#/components/schemas/key'
'400':
$ref: '#/components/responses/400ActivateKey'
'409':
$ref: '#/components/responses/409ActivateKeyConflict'
/inactiveKeys:
post:
operationId: deactivateKey
security:
- apiKey: []
accessToken:
- data/write
summary: Deactivate a key
tags:
- Key States
description: >-
Update a key by adding it to the set of inactive keys. This changes the `state` property of the key to `inactive`. This operation is available
via the `apiture:deactivate` link on the key resource, if and only if the key is eligible for the deactivate operation. The API key is also
removed from the target environment. The response is the updated representation of the key.
parameters:
- $ref: '#/components/parameters/keyQueryParam'
- $ref: '#/components/parameters/noNotificationQueryParam'
responses:
'200':
description: OK. The operation succeeded. The key was updated and its `state` changed to `inactive`.
content:
application/hal+json:
schema:
$ref: '#/components/schemas/key'
application/json:
schema:
$ref: '#/components/schemas/key'
'400':
$ref: '#/components/responses/400DeactivateKey'
'409':
$ref: '#/components/responses/409DeactivateKeyConflict'
/keys:
get:
summary: Return a collection of keys
description: >-
Return a [paginated](http://developer.apiture.com/docs/concepts/pagination) [filterable](http://developer.apiture.com/docs/concepts/filtering)
collection of keys. The [links](http://developer.apiture.com/docs/concepts/links) in the response include pagination links.
The authenticated user can only access keys for applications in their partner domain (i.e. developers registered with validated emails with a
`@mycompany.com` email domain can only see keys for that company), the discoverer key, and their own explorer key.
operationId: getKeys
security:
- apiKey: []
accessToken:
- data/read
x-apiture-implemented: true
tags:
- Key
parameters:
- $ref: '#/components/parameters/startQueryParam'
- name: limit
in: query
description: The maximum number of key representations to return in this page.
schema:
type: integer
format: int32
default: 100
- name: application
in: query
description: >-
Filter API keys to only those for this client application. The value is the client application ID. This value is merged with the
`?filter=` parameter (if any) and `?environment=` parameter (if any) with an implicit `and`.
schema:
type: string
- name: partner
in: query
description: >-
Filter API keys to only those for this partner organization. The value is the partner ID or partner domain. This value is merged with the
`?filter=` parameter (if any) and `?environment=` parameter (if any) with an implicit `and`.
schema:
type: string
- name: environment
in: query
description: >-
Filter API keys to only those for this environment. The value is the environment ID. This value is merged with the `?filter=` parameter
and `?application` or `?partner` parameter with an implicit `and`.
schema:
type: string
- $ref: '#/components/parameters/filterQueryParam'
- $ref: '#/components/parameters/stateQueryParam'
responses:
'200':
description: OK
content:
application/hal+json:
schema:
$ref: '#/components/schemas/keys'
application/json:
schema:
$ref: '#/components/schemas/keys'
'400':
$ref: '#/components/responses/400'
'422':
$ref: '#/components/responses/422'
post:
summary: Create a new key
description: >-
Create a new key in the `keys` collection. The key's `state` is initially `pending` but will change to `active` when the key has been deployed
in the target environment.
The associated client application and the target API environment to must be passed in the `href` of the corresponding `_links` in the request:
* `apiture:clientApplication`
* `apiture:environment`
This fails if there is an existing key in the `pending`, `active` or `inactive` state for the named client application and API environment.
The key's `type` is set to `partner` or `production`, depending on the type of the key's environment.
operationId: createKey
security:
- apiKey: []
accessToken:
- data/write
x-apiture-implemented: true
tags:
- Key
parameters:
- $ref: '#/components/parameters/noNotificationQueryParam'
responses:
'201':
description: Created
headers:
Location:
description: >-
The URI of the new resource. If the URI begins with / it is relative to the API root context. Else, it is a full URI starting with
*`scheme`*`://host`
schema:
type: string
format: uri
content:
application/hal+json:
schema:
$ref: '#/components/schemas/key'
application/json:
schema:
$ref: '#/components/schemas/key'
'400':
$ref: '#/components/responses/400'
'403':
$ref: '#/components/responses/403Key'
'409':
$ref: '#/components/responses/409Key'
requestBody:
content:
application/hal+json:
schema:
$ref: '#/components/schemas/createKey'
application/json:
schema:
$ref: '#/components/schemas/createKey'
description: The data necessary to create a new key.
required: true
'/keys/{keyId}':
get:
summary: Fetch a representation of this key
description: 'Return a [HAL](http://developer.apiture.com/docs/concepts/hal) representation of this key resource.'
operationId: getKey
security:
- apiKey: []
accessToken:
- data/read
x-apiture-implemented: true
tags:
- Key
parameters:
- $ref: '#/components/parameters/keyIdPathParam'
responses:
'200':
description: OK
content:
application/hal+json:
schema:
$ref: '#/components/schemas/key'
application/json:
schema:
$ref: '#/components/schemas/key'
'404':
$ref: '#/components/responses/404Key'
put:
summary: Update this key
description: Perform a complete replacement of this key.
operationId: updateKey
security:
- apiKey: []
accessToken:
- data/write
x-apiture-implemented: true
tags:
- Key
parameters:
- $ref: '#/components/parameters/keyIdPathParam'
responses:
'200':
description: OK
content:
application/hal+json:
schema:
$ref: '#/components/schemas/key'
application/json:
schema:
$ref: '#/components/schemas/key'
'400':
$ref: '#/components/responses/400'
'404':
$ref: '#/components/responses/404Key'
'422':
$ref: '#/components/responses/422'
requestBody:
content:
application/hal+json:
schema:
$ref: '#/components/schemas/key'
application/json:
schema:
$ref: '#/components/schemas/key'
required: true
patch:
summary: Update this key
description: Perform a partial update of this key. Fields which are omitted are not updated. Nested `_embedded` and `_links` are ignored if included.
operationId: patchKey
security:
- apiKey: []
accessToken:
- data/write
x-apiture-implemented: true
tags:
- Key
parameters:
- $ref: '#/components/parameters/keyIdPathParam'
responses:
'200':
description: OK
content:
application/hal+json:
schema:
$ref: '#/components/schemas/key'
application/json:
schema:
$ref: '#/components/schemas/key'
'400':
$ref: '#/components/responses/400'
'404':
$ref: '#/components/responses/404Key'
'422':
$ref: '#/components/responses/422'
requestBody:
content:
application/hal+json:
schema:
$ref: '#/components/schemas/key'
application/json:
schema:
$ref: '#/components/schemas/key'
required: true
delete:
summary: Delete this key resource
description: Delete this key resource and any resources that are owned by it.
operationId: deleteKey
security:
- apiKey: []
accessToken:
- data/delete
x-apiture-implemented: true
tags:
- Key
parameters:
- $ref: '#/components/parameters/keyIdPathParam'
responses:
'204':
$ref: '#/components/responses/204Deleted'
/discovererKey:
get:
summary: Return the Discoverer Key
description: >-
Returns the active Discoverer Key. If the Discoverer Key has not been created, this call creates, activates, and returns it. The key's `type`
is set to `discoverer`. If the key exists, it is returned.
The Discoverer Key is associated with the Dev Portal application and is only valid in the DevBank environment.
operationId: getDiscovererKey
tags:
- Discoverer Key
security:
- apiKey: []
x-apiture-implemented: true
responses:
'200':
description: OK.
content:
application/hal+json:
schema:
$ref: '#/components/schemas/discovererKey'
application/json:
schema:
$ref: '#/components/schemas/discovererKey'
'404':
description: Not Found; the Discoverer Key has not been created yet.
content:
application/hal+json:
schema:
$ref: '#/components/schemas/errorResponse'
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
post:
summary: Create or recycle the Discoverer Key
description: |-
Creates or recycles the Discoverer Key.
If the Discoverer Key has not been created, this call
creates, activates, and returns it.
If the key exists, the old key is recycled (scheduled
to be removed but left active) and a new Discoverer key is created, activated, and returned.
If the request body contains new credentials for the sample user,
the service saves those new credentials used for creating the discoverer key and
discoverer access token.
The Discoverer Key is associated with the Dev Portal
application and is only valid in the DevBank environment.
*Only the administrator or system can create or recycle the discoverer key.*
operationId: discovererKey
tags:
- Discoverer Key
security:
- apiKey: []
accessToken:
- admin/read
- admin/write
x-apiture-implemented: true
responses:
'200':
description: OK.
content:
application/hal+json:
schema:
$ref: '#/components/schemas/key'
application/json:
schema:
$ref: '#/components/schemas/key'
'201':
description: Created
headers:
Location:
description: The URL of the new Explorer key
schema:
type: string
format: uri
content:
application/hal+json:
schema:
$ref: '#/components/schemas/key'
application/json:
schema:
$ref: '#/components/schemas/key'
'400':
$ref: '#/components/responses/400'
'403':
description: Forbidden. The user is not allowed to request an explorer API key for this restricted environment.
content:
application/hal+json:
schema:
$ref: '#/components/schemas/errorResponse'
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
'422':
description: |-
Unprocessable Entity. The request body could not be processed.
This error response may have one of the following `type` values:
* [`passwordRequired`](#err-passwordRequired)
x-apiture-errors:
- passwordRequired
content:
application/hal+json:
schema:
$ref: '#/components/schemas/errorResponse'
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
requestBody:
content:
application/hal+json:
schema:
$ref: '#/components/schemas/discoverKeyRequest'
application/json:
schema:
$ref: '#/components/schemas/discoverKeyRequest'
description: >-
Optional credentials to reset the user name and password of the sample user used for creating/refreshing the discoverer key and access
token.
required: true
/explorerKey:
get:
summary: Return the user's Explorer Key
description: >-
Returns the user's Explorer Key for a target environmet.
An Explorer Key is associated with the Dev Portal application client application and one of the target environments associated with the dev
portal. (Thus, a user may have multiple explorer keys, one per environment.)
operationId: getExplorerKey
tags:
- Explorer Key
security:
- apiKey: []
accessToken:
- data/read
parameters:
- $ref: '#/components/parameters/environmentQueryParam'
x-apiture-implemented: true
responses:
'200':
description: OK.
content:
application/hal+json:
schema:
$ref: '#/components/schemas/key'
application/json:
schema:
$ref: '#/components/schemas/key'
'403':
description: Forbidden. The user is not allowed to request an explorer API key for this restricted environment.
content:
application/hal+json:
schema:
$ref: '#/components/schemas/errorResponse'
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
'404':
description: Not Found; the Explorer Key has not been created yet.
content:
application/hal+json:
schema:
$ref: '#/components/schemas/errorResponse'
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
post:
summary: Create or recycles the user's Explorer Key
description: >-
Creates and returns the user's Explorer Key. If the Explorer Key has not been created, this call creates and returns it, but leaves it in a
`pending` state, awaiting administrator approval. If the key exists, the old key is recycled (scheduled to be removed but left active) and a
new Explorer key is created, activated, and returned. The key's `type` is set to `explorer`.
The Explorer Key is specific and private to the current authenticated user. It has a `name` which is the concatenation of the user's user name
(email address), `"Explorer"`, such as `"walter.black@cool.example.com Explorer"`.
The Explorer Key is associated with the Dev Portal application and is only valid in the DevBank environment or where the domain name of the
user's email address is listed in the API environment's `domains`.
operationId: explorerKey
tags:
- Explorer Key
security:
- apiKey: []
accessToken:
- data/read
- data/write
parameters:
- $ref: '#/components/parameters/environmentQueryParam'
x-apiture-implemented: true
responses:
'200':
description: OK.
headers:
Location:
description: The URL of the new Explorer key
schema:
type: string
format: uri
content:
application/hal+json:
schema:
$ref: '#/components/schemas/key'
application/json:
schema:
$ref: '#/components/schemas/key'
'201':
description: Created
headers:
Location:
description: The URL of the new Explorer key
schema:
type: string
format: uri
content:
application/hal+json:
schema:
$ref: '#/components/schemas/key'
application/json:
schema:
$ref: '#/components/schemas/key'
'403':
description: Forbidden. The user is not allowed to request an explorer API key for this restricted environment.
content:
application/hal+json:
schema:
$ref: '#/components/schemas/errorResponse'
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
/explorerKey/sampleDataGeneration:
post:
summary: Create sample data for the user
description: |-
Create sample data for the user using their explorer key.
This operation is only called from `createSampleDataRequest`
to start the data generation asynchronously.
This operation does not use a request body.
**Note** This operation will move from this API to
a dev portal `users` API, but that API does not yet exist.
operationId: generateSampleData
tags:
- Explorer Key
security:
- apiKey: []
accessToken:
- data/read
- data/write
parameters:
- name: requestId
in: query
required: true
description: >-
A reference to the internal sample data request containing the user, explorer key, environment, and environment token. This `requestId` is
generated from the [`createSampleDataRequest`](#op-createSampleDataRequest) operation.
schema:
type: string
responses:
'202':
description: Accepted. The request was accepted and will be processed.
content:
application/hal+json:
schema:
$ref: '#/components/schemas/sampleDataRequest'
application/json:
schema:
$ref: '#/components/schemas/sampleDataRequest'
/explorerKey/sampleDataRequest:
get:
summary: Check sample data request status
description: |-
Return the status of the sample data request
for an environment. The `state` property conveys the status
of the request.
**Note** This operation will move from this API to
a dev portal `users` API, but that API does not yet exist.
operationId: checkSampleDataRequest
tags:
- Explorer Key
security:
- apiKey: []
accessToken:
- data/read
parameters:
- $ref: '#/components/parameters/environmentQueryParam'
- $ref: '#/components/parameters/environmentTokenQueryParam'
responses:
'200':
description: OK.
content:
application/hal+json:
schema:
$ref: '#/components/schemas/sampleDataRequest'
application/json:
schema:
$ref: '#/components/schemas/sampleDataRequest'
'400':
$ref: '#/components/responses/400'
post:
summary: Create sample data for the user
description: |-
Create sample data for the user using their explorer key.
This creates an account for the user
and then runs the transaction tool to create some
finctional historical transactions for the user.
If invoked multiple times, it will run the processes
again. This operation is asynchronous.
The explorer key must be `active`.
This operation does not use a request body.
**Note** This operation will move from this API to
a dev portal `users` API, but that API does not yet exist.
operationId: createSampleDataRequest
tags:
- Explorer Key
security:
- apiKey: []
accessToken:
- data/read
- data/write
parameters:
- $ref: '#/components/parameters/environmentQueryParam'
- $ref: '#/components/parameters/environmentTokenQueryParam'
responses:
'202':
description: Accepted. The request was accepted and will be processed.
content:
application/hal+json:
schema:
$ref: '#/components/schemas/sampleDataRequest'
application/json:
schema:
$ref: '#/components/schemas/sampleDataRequest'
'400':
$ref: '#/components/responses/400'
'409':
description: 'Conflict. The process is already running, or the explorer key is not active, or some other situation prevents creating sample data.'
content:
application/hal+json:
schema:
$ref: '#/components/schemas/errorResponse'
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
/explorerKey/sampleDataRequest/counter:
post:
summary: Reset a user's sample data request counter
description: >-
The API enforces a limit of the number of times a user may request sample data. However, if the sample generation fails repeatedly for the
user, they may reach the limit without any data being generated for them. An administrator can use this operation to reset the counter back to
zero so the user can try again.
operationId: resetSampleDataRequestCounter
tags:
- Explorer Key
security:
- apiKey: []
accessToken:
- admin/write
responses:
'202':
description: Accepted. The request was accepted and will be processed.
content:
application/hal+json:
schema:
$ref: '#/components/schemas/sampleDataCounterReset'
application/json:
schema:
$ref: '#/components/schemas/sampleDataCounterReset'
'400':
$ref: '#/components/responses/400'
requestBody:
content:
application/hal+json:
schema:
$ref: '#/components/schemas/sampleDataCounterReset'
application/json:
schema:
$ref: '#/components/schemas/sampleDataCounterReset'
description: Request resetting the samle data counter back to zero for a user.
required: true
/explorerKeys:
get:
summary: Get a Explorer Keys
description: Return the explorer keys for a partner domain or user. This is an admin-only operation.
operationId: getExplorerKeys
security:
- apiKey: []
accessToken:
- admin/read
x-apiture-implemented: true
tags:
- Explorer Key
parameters:
- name: owner
description: Filter API keys to only those keys for this owner's email address.
in: query
schema:
type: string
format: email
- name: environment
in: query
description: 'Filter API keys to only those keys whose environment ID, name, or hostname match this value.'
schema:
type: string
- $ref: '#/components/parameters/stateQueryParam'
- name: filter
in: query
description: >-
Optional filter criteria. See [filtering](http://developer.apiture.com/docs/concepts/filtering).
This collection may be filtered by
following properties and functions:
schema:
type: string
- $ref: '#/components/parameters/startQueryParam'
- name: limit
in: query
description: The maximum number of key representations to return in this page.
schema:
type: integer
format: int32
default: 100
x-apiture-traits:
filtering:
owner:
filters: 'eq, in, contains'
partner:
filters: 'eq, in, contains'
environment:
filters: 'eq, in, contains'
responses:
'200':
description: OK
content:
application/hal+json:
schema:
$ref: '#/components/schemas/explorerKeys'
application/json:
schema:
$ref: '#/components/schemas/explorerKeys'
'400':
$ref: '#/components/responses/400'
'422':
$ref: '#/components/responses/422'
/:
get:
summary: Top-level resources and operations in this API
description: Return links to the top-level resources and operations in this API.
operationId: getApi
security:
- apiKey: []
x-apiture-implemented: true
responses:
'200':
description: OK
content:
application/hal+json:
schema:
$ref: '#/components/schemas/root'
application/json:
schema:
$ref: '#/components/schemas/root'
tags:
- API
/apiDoc:
get:
summary: Return API definition document
description: Return the OpenAPI document that describes this API.
operationId: getApiDoc
security:
- apiKey: []
x-apiture-implemented: true
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
application/openapi+json;version=2.0:
schema:
type: object
application/openapi+yaml;version=2.0:
schema:
type: object
application/hal+json:
schema:
type: object
tags:
- API
x-apiture-errors:
passwordRequired:
description: 'When updating the discoverer key credentials, the `sampleUserPassword` property is required if the request incldues the `sampleUserName`.'
remediation: Pass `sampleUserPassword` if the request incldues the `sampleUserName`.
keyRefNotFound:
description: The key parameter was malformed or does not refer to an existing or accessible key.
remediation: Pass a valid key in the key query parameter.
invalidPartnerDomain:
description: The current user's email address is associated with a restricted partner organization domain.
remediation: 'Register using a company email address, not an email service.'
x-apiture-traits:
- api:
title: API Keys
basePath: apiKeys
description: Manage API keys for secure API access.
links:
- getApi
- getApiDoc
- getKeys
- createKey
- getDiscovererKey
- discovererKey
- getExplorerKey
- explorerKey
applied: true
- resource:
name: key
description: 'An API Key, for secure access to Apiture APIs'
etag: false
simpleModelSchema: true
sortable: false
searchable: false
cursor: true
applied: true
- state:
state: inactive
verb: deactivate
name: key
applied: true
- state:
state: active
verb: activate
name: key
applied: true
x-apiture-annotated-at: '2020-10-23T17:06:33.888Z'
components:
schemas:
keyFields:
title: Key Fields (v1.0.0)
description: Properties used in other API key schemas.
x-apiture-fragment: true
type: object
properties:
name:
description: >-
The name of the API key. If not passed when creating a key, the name is derived by concatenating the application name, the parter
organization domain name,and the key's type. Names need not be unique (each key's `_id` is generated by the server and unique).
type: string
minLength: 6
maxLength: 128
x-apiture-version: 1.0.0
x-apiture-flattened: true
createKey:
title: Create Key (v1.0.0)
description: >
Request body to create a new API key. The request **must** contain links as described in the `createKey` schema. The `type` of the key is
determined by the environment's type.
Links
Response and request bodies using this createKey
schema may contain
the following links:
Rel | Summary | Method |
apiture:clientApplication |
| GET |
apiture:environment |
| GET |
x-apiture-links:
- rel: 'apiture:clientApplication'
summary: 'Client application (`/clientApplications/applications/{applicationId}`)'
- rel: 'apiture:environment'
summary: 'API Environment resource (`apiEnvironments/environments/{environmentId}`)'
example:
name: 3rd Party Bank web application at api.3rdparty.bank (production)
_links:
'apiture:clientApplication':
href: 'https://api.developer.apiture.com/clientApplications/applications/dd5122bd-a8cd-4d23-a001-d29fcdf346cc'
'apiture:environment':
href: 'https://api.developer.apiture.com/apiEnvironments/environments/d85d9eb2-4d4b-4cdf-8b69-5a3ea0ddfaac'
x-apiture-version: 1.0.0
x-apiture-composition:
- $ref: '#/components/schemas/abstractResource'
- $ref: '#/components/schemas/keyFields'
properties:
_links:
description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
allOf:
- $ref: '#/components/schemas/links'
_embedded:
description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
type: object
_profile:
description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.'
type: string
format: uri
_error:
description: An object which describes an error. This value is omitted if the operation succeeded without error.
type: object
allOf:
- $ref: '#/components/schemas/error'
name:
description: >-
The name of the API key. If not passed when creating a key, the name is derived by concatenating the application name, the parter
organization domain name,and the key's type. Names need not be unique (each key's `_id` is generated by the server and unique).
type: string
minLength: 6
maxLength: 128
type: object
x-apiture-flattened: true
key:
title: Key (v1.0.0)
description: |
API key resources.
Links
Response and request bodies using this key
schema may contain
the following links:
example:
_profile: 'https://api.apiture.com/schemas/apiKeys/key/v1.0.0/profile.json'
_id: 0399abed-fd3d-4830-a88b-30f38b8a365c
name: My Apiture POC
key: 295fd0e8b0b449f9a5a3dbfd4a3e3149
clientId: 1b97ad67397640c89208bdfd1e039b1f
clientSecret: 5035cef945054f96a56d07620652b6bf
applicationName: My Apiture POC
partnerName: Example FinTex
partnerDomain: fintech.example.com
_links:
'apiture:clientApplication':
href: 'https://api.developer.apiture.com/clientApplications/applications/00aaf46d-05c2-4237-9305-fd9ed9c4994b'
'apiture:partner':
href: 'https://api.developer.apiture.com/partners/organizations/2435a7f0-2650-49df-9988-c113e36e3c96'
'apiture:environment':
href: 'https://api.developer.apiture.com/apiEnvironments/environments/8c112888-f139-4583-bb0e-cbd378550a48'
'apiture:deactivate':
href: 'https://api.developer.apiture.com/apiKeys/inactiveKeys?key=0399abed-fd3d-4830-a88b-30f38b8a365c'
x-apiture-links:
- rel: 'apiture:activate'
operationId: activateKey
- rel: 'apiture:deactivate'
operationId: deactivateKey
x-apiture-version: 1.0.0
x-apiture-composition:
- $ref: '#/components/schemas/abstractResource'
- $ref: '#/components/schemas/keyFields'
- properties:
- _id
- key
- applicationName
- environmentName
- environmentHost
- partnerName
- partnerDomain
- clientId
- clientSecret
- type
- state
- createdAt
- expiresAt
properties:
_links:
description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
allOf:
- $ref: '#/components/schemas/links'
_embedded:
description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
type: object
_profile:
description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.'
type: string
format: uri
_error:
description: An object which describes an error. This value is omitted if the operation succeeded without error.
type: object
allOf:
- $ref: '#/components/schemas/error'
name:
description: >-
The name of the API key. If not passed when creating a key, the name is derived by concatenating the application name, the parter
organization domain name,and the key's type. Names need not be unique (each key's `_id` is generated by the server and unique).
type: string
minLength: 6
maxLength: 128
_id:
description: The resource ID of this API key resource. This is _not_ the actual API Key; the `API-Key` header is the `key` property.
type: string
minLength: 6
maxLength: 40
readOnly: true
key:
description: 'The value of the API key, to be used in the `API-Key` request header on API calls.'
type: string
minLength: 6
maxLength: 64
readOnly: true
applicationName:
description: >-
The name of the client application for this API key. This is derived from the `apiture:clientApplication` resource passed in at creation
time.
type: string
minLength: 4
maxLength: 64
example: My Apiture POC
readOnly: true
environmentName:
description: 'The name of the API environment for this API key. This is derived from the `apiture:environment` resource passed in at creation time.'
type: string
minLength: 6
maxLength: 64
example: DevBank
readOnly: true
environmentHost:
description: 'The name of the API environment host for this API key. This is derived from the `apiture:environment` resource passed in at creation time.'
type: string
minLength: 4
maxLength: 64
example: api.devbank.apiture.com
readOnly: true
partnerName:
description: The name of the optional partner organization/company. This is derived from the partner organization associated with the application.
type: string
minLength: 4
maxLength: 128
readOnly: true
example: Example FinTex
partnerDomain:
description: >-
The web domain of the optional partner organization/company. This is derived from the partner organization associated with the
application.
type: string
minLength: 4
maxLength: 128
example: fintech.example.com
readOnly: true
format: urn
clientId:
description: The client ID porton of the client credentials associated with the API key.
type: string
minLength: 6
maxLength: 128
readOnly: true
clientSecret:
description: The client secret porton of the client credentials associated with the API key.
type: string
minLength: 6
maxLength: 128
readOnly: true
type:
description: Defines what type of key this is.
allOf:
- $ref: '#/components/schemas/keyType'
readOnly: true
state:
description: >-
The current state of the key. This is immutable and derived, based on the actions to activate or deactivate the key via the `activateKey`
and `deactivateKey` operations. The initial state is `pending`; it changes to `active` when the API key and credentials have been deployed
into the target environment via the `activateKey` operation.
allOf:
- $ref: '#/components/schemas/keyState'
readOnly: true
createdAt:
description: The date-time when the key was created. This is an RFC 3336 formatted string in UTC time.
type: string
format: date-time
readOnly: true
example: {}
expiresAt:
description: >-
The date-time when the key expires. If this is omitted, the key does not have an expiration time. (This expiration is typically is used
only for Discoverer keys). This is an RFC 3336 formatted string in UTC time.
type: string
format: date-time
readOnly: true
example: {}
type: object
x-apiture-flattened: true
keyState:
title: Key State (v1.0.0)
description: |+
Possible state of an API key.
keyState
strings may have one of the following
[enumerated values](https://developer.apiture.com/concepts/label-groups#enumerations):
Value | Description |
pending | Pending: A key that has been requested but not activated (not approved). |
active | Active: A key that has been approved and is active. |
inactive | Inactive: A key that has been revoked and is not active. |
type: string
x-apiture-enum: keyState
enum:
- pending
- active
- inactive
x-apiture-version: 1.0.0
x-apiture-flattened: true
keyType:
title: Key Type (v1.0.0)
description: |+
The type describe the purpose and use of the API key. This field is derived from the target environment used when the key is created.
keyType
strings may have one of the following
[enumerated values](https://developer.apiture.com/concepts/label-groups#enumerations):
Value | Description |
discoverer | Discoverer Key: The Discoverer Key is for unauthenticated users to explore the Apiture APIs in a limited manner, using a sample user ("John Smith") identity. The Discoverer Key is shared by all unauthenticated users. It is recycled on a periodic basis: a new Discoverer key is minted each day to replace the old one, and the old one is then revoked, marked as expired, and deleted at some time after that. |
explorer | Explorer Key: An Explorer key is for authenticated users to explore
the Apiture APIs in more depth. It is provisioned after
a user registers (moderated by the portal admin).
Using this, the developer can also create sample
data that only they can access (bank accounts, etc.).
The user can view their Explorer key via their
My Account page on the developer portal. |
partner | Partner Key: Partner keys are associated with a specific client partner organization (company), a registered client application, and a specific runtime environment (such as a dev, test, or other environment. |
production | Production Key: Production keys are partner keys that are attached to a production (non-test, non-development) environment. |
private | Private Key: Private keys are for Apiture use only. |
type: string
x-apiture-enum: keyType
enum:
- discoverer
- explorer
- partner
- production
- private
x-apiture-version: 1.0.0
x-apiture-flattened: true
discovererKey:
title: Discoverer Key (v1.0.0)
description: An API key and access token for an unauthenticated user to make API calls against the devbank target environment.
x-apiture-version: 1.0.0
x-apiture-composition:
- $ref: '#/components/schemas/abstractResource'
- properties:
- apiKey
- accessToken
properties:
_links:
description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
allOf:
- $ref: '#/components/schemas/links'
_embedded:
description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
type: object
_profile:
description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.'
type: string
format: uri
_error:
description: An object which describes an error. This value is omitted if the operation succeeded without error.
type: object
allOf:
- $ref: '#/components/schemas/error'
apiKey:
description: The API key for Discoverer use.
allOf:
- $ref: '#/components/schemas/key'
accessToken:
description: >-
An OAuth access token which may be used for API calls on the devbank envirornment. This token expires every hour. The client should fetch
a new access token before this expires.
type: string
type: object
x-apiture-flattened: true
explorerKeys:
title: Explorer Keys List (v1.0.0)
description: Collection of explorer keys.
example:
_profile: 'https://api.apiture.com/schemas/apiKeys/explorerKeys/v1.0.0/profile.json'
start: g434ljkf430
limit: 10
name: keys
_links:
self:
href: 'https://api.developer.apiture.com/apiKeys/explorerKeys'
next:
href: 'https://api.developer.apiture.com/apiKeys/keys?start=p4900sk3df9&limit=10'
_embedded:
items:
_id: 0399abed-fd3d-4830-a88b-30f38b8a365c
owner: Walter.Black@example.com
_profile: 'https://api.apiture.com/schemas/apiKeys/explorerKey/v1.0.0/profile.json'
name: Explorer Key Walter.Black@example.com
key: 295fd0e8b0b449f9a5a3dbfd4a3e3149
clientId: 1b97ad67397640c89208bdfd1e039b1f
clientSecret: 5035cef945054f96a56d07620652b6bf
applicationName: Dev Portal
partnerName: Example
partnerDomain: example.com
_links:
'apiture:clientApplication':
href: 'https://api.developer.apiture.com/clientApplications/applications/00aaf46d-05c2-4237-9305-fd9ed9c4994b'
'apiture:partner':
href: 'https://api.developer.apiture.com/partners/organizations/2435a7f0-2650-49df-9988-c113e36e3c96'
'apiture:environment':
href: 'https://api.developer.apiture.com/apiEnvironments/environments/8c112888-f139-4583-bb0e-cbd378550a48'
'apiture:deactivate':
href: 'https://api.developer.apiture.com/apiKeys/inactiveKeys?key=0399abed-fd3d-4830-a88b-30f38b8a365c'
self:
href: 'https://api.developer.apiture.com/apiKeys/keys/0399abed-fd3d-4830-a88b-30f38b8a365c'
x-apiture-version: 1.0.0
x-apiture-composition:
- $ref: '#/components/schemas/cursorPagedCollection'
- properties:
- _embedded
properties:
_links:
description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
allOf:
- $ref: '#/components/schemas/links'
_embedded:
type: object
description: Embedded objects.
properties:
items:
description: An array containing a page of key items.
type: array
items:
$ref: '#/components/schemas/explorerKey'
_profile:
description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.'
type: string
format: uri
_error:
description: An object which describes an error. This value is omitted if the operation succeeded without error.
type: object
allOf:
- $ref: '#/components/schemas/error'
start:
description: >-
An opaque marker representing the position of the current page in this resource collection. The service will use the `start` and `limit`
to compute the `?start=` query parameter for the next page when it provides the `next` link in the collection's `_links`.
type: string
limit:
description: The maximum number of items per page.
type: integer
name:
description: A name for the items in collection.
type: string
type: object
x-apiture-flattened: true
explorerKey:
title: Explorer Key (v1.0.0)
description: A user's explorer key.
x-apiture-version: 1.0.0
x-apiture-composition:
- $ref: '#/components/schemas/key'
- properties:
- owner
properties:
_links:
description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
allOf:
- $ref: '#/components/schemas/links'
_embedded:
description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
type: object
_profile:
description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.'
type: string
format: uri
_error:
description: An object which describes an error. This value is omitted if the operation succeeded without error.
type: object
allOf:
- $ref: '#/components/schemas/error'
name:
description: >-
The name of the API key. If not passed when creating a key, the name is derived by concatenating the application name, the parter
organization domain name,and the key's type. Names need not be unique (each key's `_id` is generated by the server and unique).
type: string
minLength: 6
maxLength: 128
_id:
description: The resource ID of this API key resource. This is _not_ the actual API Key; the `API-Key` header is the `key` property.
type: string
minLength: 6
maxLength: 40
readOnly: true
key:
description: 'The value of the API key, to be used in the `API-Key` request header on API calls.'
type: string
minLength: 6
maxLength: 64
readOnly: true
applicationName:
description: >-
The name of the client application for this API key. This is derived from the `apiture:clientApplication` resource passed in at creation
time.
type: string
minLength: 4
maxLength: 64
example: My Apiture POC
readOnly: true
environmentName:
description: 'The name of the API environment for this API key. This is derived from the `apiture:environment` resource passed in at creation time.'
type: string
minLength: 6
maxLength: 64
example: DevBank
readOnly: true
environmentHost:
description: 'The name of the API environment host for this API key. This is derived from the `apiture:environment` resource passed in at creation time.'
type: string
minLength: 4
maxLength: 64
example: api.devbank.apiture.com
readOnly: true
partnerName:
description: The name of the optional partner organization/company. This is derived from the partner organization associated with the application.
type: string
minLength: 4
maxLength: 128
readOnly: true
example: Example FinTex
partnerDomain:
description: >-
The web domain of the optional partner organization/company. This is derived from the partner organization associated with the
application.
type: string
minLength: 4
maxLength: 128
example: fintech.example.com
readOnly: true
format: urn
clientId:
description: The client ID porton of the client credentials associated with the API key.
type: string
minLength: 6
maxLength: 128
readOnly: true
clientSecret:
description: The client secret porton of the client credentials associated with the API key.
type: string
minLength: 6
maxLength: 128
readOnly: true
type:
description: Defines what type of key this is.
allOf:
- $ref: '#/components/schemas/keyType'
readOnly: true
state:
description: >-
The current state of the key. This is immutable and derived, based on the actions to activate or deactivate the key via the `activateKey`
and `deactivateKey` operations. The initial state is `pending`; it changes to `active` when the API key and credentials have been deployed
into the target environment via the `activateKey` operation.
allOf:
- $ref: '#/components/schemas/keyState'
readOnly: true
createdAt:
description: The date-time when the key was created. This is an RFC 3336 formatted string in UTC time.
type: string
format: date-time
readOnly: true
example: {}
expiresAt:
description: >-
The date-time when the key expires. If this is omitted, the key does not have an expiration time. (This expiration is typically is used
only for Discoverer keys). This is an RFC 3336 formatted string in UTC time.
type: string
format: date-time
readOnly: true
example: {}
owner:
description: The email address of the owner.
type: string
format: email
type: object
x-apiture-flattened: true
keys:
title: Key Collection (v1.0.0)
description: |-
Collection of keys. The items in the collection are ordered in the `_embedded.items` array; the `name` is `keys`.
The top-level `_links` object may contain pagination links: `self`, `next`, `prev`, `first`, `last`, `collection`.
example:
_profile: 'https://api.apiture.com/schemas/apiKeys/keys/v1.0.0/profile.json'
start: g434ljkf430
limit: 10
name: keys
_links:
self:
href: 'https://api.developer.apiture.com/apiKeys/keys?start=g434ljkf430&limit=10'
next:
href: 'https://api.developer.apiture.com/apiKeys/keys?start=p4900sk3df9&limit=10'
collection:
href: 'https://api.developer.apiture.com/apiKeys/keys'
_embedded:
items:
anyOf:
- _id: 0399abed-fd3d-4830-a88b-30f38b8a365c
_profile: 'https://api.apiture.com/schemas/apiKeys/key/v1.0.0/profile.json'
_links:
self:
href: 'https://api.developer.apiture.com/apiKeys/keys/0399abed-fd3d-4830-a88b-30f38b8a365c'
- _id: d62c0701-0d74-4836-83f9-ebf3709442ea
_profile: 'https://api.apiture.com/schemas/apiKeys/key/v1.0.0/profile.json'
_links:
self:
href: 'https://api.developer.apiture.com/apiKeys/keys/d62c0701-0d74-4836-83f9-ebf3709442ea'
x-apiture-version: 1.0.0
x-apiture-composition:
- $ref: '#/components/schemas/cursorPagedCollection'
- properties:
- _embedded
properties:
_links:
description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
allOf:
- $ref: '#/components/schemas/links'
_embedded:
type: object
description: Embedded objects.
properties:
items:
description: An array containing a page of key items.
type: array
items:
$ref: '#/components/schemas/key'
_profile:
description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.'
type: string
format: uri
_error:
description: An object which describes an error. This value is omitted if the operation succeeded without error.
type: object
allOf:
- $ref: '#/components/schemas/error'
start:
description: >-
An opaque marker representing the position of the current page in this resource collection. The service will use the `start` and `limit`
to compute the `?start=` query parameter for the next page when it provides the `next` link in the collection's `_links`.
type: string
limit:
description: The maximum number of items per page.
type: integer
name:
description: A name for the items in collection.
type: string
type: object
x-apiture-flattened: true
discoverKeyRequest:
title: Discover Key Request (v1.0.0)
description: >-
Data the admin can pass when creating or recycling the discoverer key. This is optional, but may contain new credentials for the sample user.
If `sampleUserName` is passed, the request must also contain `sampleUserPassword`. If only `sampleUserPassword` is passed, the request will
update the password for the current sample user.
type: object
properties:
sampleUserName:
description: The user name (login userid) of the user used for sample data. This user must exist in the devbank environment used by the portal.
type: string
format: email
example: user.name@example.com
sampleUserPassword:
description: The password of the sample user.
type: string
x-apiture-version: 1.0.0
x-apiture-flattened: true
sampleDataRequest:
title: Sample Data Request (v1.0.0)
description: |
Reflects a user's request to create sample data in an environment.
Links
Response and request bodies using this sampleDataRequest
schema may contain
the following links:
Rel | Summary | Method |
apiture:environment |
| GET |
x-apiture-links:
- rel: 'apiture:environment'
summary: 'API Environment resource (`apiEnvironments/environments/{environmentId}`)'
x-apiture-version: 1.0.0
x-apiture-composition:
- $ref: '#/components/schemas/abstractResource'
- properties:
- state
- environmentId
- environmentName
properties:
_links:
description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
allOf:
- $ref: '#/components/schemas/links'
_embedded:
description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
type: object
_profile:
description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.'
type: string
format: uri
_error:
description: An object which describes an error. This value is omitted if the operation succeeded without error.
type: object
allOf:
- $ref: '#/components/schemas/error'
state:
description: The state of the sample data request.
allOf:
- $ref: '#/components/schemas/sampleDataRequestState'
environmentId:
description: The `_id` of the API environment.
type: string
maxLength: 64
environmentName:
description: The `name` of the API environment.
type: string
maxLength: 64
type: object
x-apiture-flattened: true
sampleDataRequestState:
title: Sample Data Request State (v1.0.0)
description: The state of the sample data request.
type: string
enum:
- none
- started
- completed
- failed
x-apiture-version: 1.0.0
x-apiture-flattened: true
sampleDataCounterReset:
title: Sample Data Counter Reset (v1.0.0)
description: A request to reset a user's sample data generation counter back to zero.
x-apiture-version: 1.0.0
required:
- username
- environment
example:
_profile: 'https://api.apiture.com/schemas/apiKeys/sampleDataCounterReset/v1.0.0/profile.json'
username: max.peck@nasa.gov
environment: api.devbank.apiture.com
x-apiture-composition:
- $ref: '#/components/schemas/abstractRequest'
- properties:
- username
- environment
properties:
_links:
description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
allOf:
- $ref: '#/components/schemas/links'
_embedded:
description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
type: object
_profile:
description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.'
type: string
format: uri
username:
description: The username (email address) that the user uses to login to the developer portal.
type: string
format: email
environment:
description: The host name of the target environment where the user is trying to generate sample data.
type: string
minLength: 8
maxLength: 64
type: object
x-apiture-flattened: true
errorResponse:
x-apiture-version: 2.0.0
title: Error Response (v2.0.0)
description: |-
Describes an error response, typically returned on 4xx or 5xx errors from API operations. The `_error` object contains the error details.
This schema was resolved from [`common/errorResponse`](https://production.api.apiture.com/schemas/common/errorResponse/v2.0.0/model.json).
example:
_profile: 'https://api.apiture.com/schemas/common/errorResponse/v2.0.0/profile.json'
_error:
_id: 2eae46e1-575c-4d69-8a8f-0a7b0115a4b3
message: The value for deposit must be greater than 0.
statusCode: 422
type: positiveNumberRequired
attributes:
value: -125.5
remediation: Provide a value which is greater than 0
occurredAt: '2018-01-25T05:50:52.375Z'
_links:
describedby:
href: 'https://api.apiture.com/errors/positiveNumberRequired'
_embedded:
errors: []
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/errorResponse/v2.0.0/model.json'
x-apiture-namespace: common
x-apiture-composition:
- $ref: '#/components/schemas/abstractResource'
properties:
_links:
description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
allOf:
- $ref: '#/components/schemas/links'
_embedded:
description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
type: object
_profile:
description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.'
type: string
format: uri
_error:
description: An object which describes an error. This value is omitted if the operation succeeded without error.
type: object
allOf:
- $ref: '#/components/schemas/error'
type: object
x-apiture-flattened: true
root:
x-apiture-version: 2.0.0
title: API Root (v2.0.0)
description: |-
A HAL response, with hypermedia `_links` for the top-level resources and operations in API.
This schema was resolved from [`common/root`](https://production.api.apiture.com/schemas/common/root/v2.0.0/model.json).
example:
id: apiName
name: API name
apiVersion: 1.0.0
_profile: 'https://production.api.apiture.com/schemas/common/root/v2.0.0/profile.json'
_links: {}
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/root/v2.0.0/model.json'
x-apiture-namespace: common
x-apiture-composition:
- $ref: '#/components/schemas/abstractResource'
- properties:
- _id
- name
- apiVersion
properties:
_links:
description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
allOf:
- $ref: '#/components/schemas/links'
_embedded:
description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
type: object
_profile:
description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.'
type: string
format: uri
_error:
description: An object which describes an error. This value is omitted if the operation succeeded without error.
type: object
allOf:
- $ref: '#/components/schemas/error'
_id:
description: This API's unique ID.
readOnly: true
type: string
name:
type: string
description: This API's name.
apiVersion:
type: string
description: This API's version.
type: object
x-apiture-flattened: true
abstractResource:
x-apiture-version: 2.0.0
title: Abstract Resource (v2.0.0)
description: >-
An abstract schema used to define other schemas for request and response bodies. This is a
[HAL](https://tools.ietf.org/html/draft-kelly-json-hal-08) resource representation. This model contains hypermedia `_links`, and either
optional domain object data with `_profile` and optional `_embedded` objects, or an `_error` object. In responses, if the operation was
successful, this object will not include the `_error`, but if the operation was a 4xx or 5xx error, this object will not include `_embedded`
or any data fields, only `_error` and optionally `_links`.
This schema was resolved from
[`common/abstractResource`](https://production.api.apiture.com/schemas/common/abstractResource/v2.0.0/model.json).
example:
_profile: 'https://production.api.apiture.com/schemas/common/abstractResource/v2.0.0/profile.json'
_links:
self:
href: 'https://api.devbank.apiture.com/applications/application/328f6bf6-d762-422f-a077-ab91ca4d0b6f'
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/abstractResource/v2.0.0/model.json'
x-apiture-namespace: common
x-apiture-composition:
- $ref: '#/components/schemas/abstractRequest'
- properties:
- _error
properties:
_links:
description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
allOf:
- $ref: '#/components/schemas/links'
_embedded:
description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
type: object
_profile:
description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.'
type: string
format: uri
_error:
description: An object which describes an error. This value is omitted if the operation succeeded without error.
type: object
allOf:
- $ref: '#/components/schemas/error'
type: object
x-apiture-flattened: true
cursorPagedCollection:
x-apiture-version: 2.0.0
title: Cursor Paged Collection (v2.0.0)
description: >-
A collection of resources, or a page from a larger collection. This is an abstract model schema which is extended to define specific resource
collections. Pages are referenced using an opaque string starting point named `start`. The `_links` in the collection may contain [pagination
links](https://developer.apiture.com/docs/concepts/pagination):
* the `next` link returns the next page of items. If there is no `next`
link, the collection has been exhausted.
* the `first` link returns to the beginning
of the filtered/sorted collection.
* the `collection` link returns
to the beginning of the default collection with no explicit filter
or sort criteria.
Cursor paged collections can only paginate forwards contiguously (without skipping items or pages), or reset to the beginning of the
collection. This pagination works for collections which are likely to change during pagination, such as adding data to the beginning of the
collection's natural sort order. Examples include transactions or audit records.
This schema was resolved from
[`common/cursorPagedCollection`](https://production.api.apiture.com/schemas/common/cursorPagedCollection/v2.0.0/model.json).
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/cursorPagedCollection/v2.0.0/model.json'
x-apiture-namespace: common
x-apiture-composition:
- $ref: '#/components/schemas/abstractResource'
- properties:
- start
- limit
- name
properties:
_links:
description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
allOf:
- $ref: '#/components/schemas/links'
_embedded:
description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
type: object
_profile:
description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.'
type: string
format: uri
_error:
description: An object which describes an error. This value is omitted if the operation succeeded without error.
type: object
allOf:
- $ref: '#/components/schemas/error'
start:
description: >-
An opaque marker representing the position of the current page in this resource collection. The service will use the `start` and `limit`
to compute the `?start=` query parameter for the next page when it provides the `next` link in the collection's `_links`.
type: string
limit:
description: The maximum number of items per page.
type: integer
name:
description: A name for the items in collection.
type: string
type: object
x-apiture-flattened: true
abstractRequest:
x-apiture-version: 2.0.0
title: Abstract Request (v2.0.0)
description: >-
An abstract schema used to define other request-only schemas. This is a [HAL](https://tools.ietf.org/html/draft-kelly-json-hal-08) resource
representation, minus the `_error` defined in `abstractResource`.
This schema was resolved from [`common/abstractRequest`](https://production.api.apiture.com/schemas/common/abstractRequest/v2.0.0/model.json).
properties:
_links:
description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
allOf:
- $ref: '#/components/schemas/links'
_embedded:
description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
type: object
_profile:
description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.'
type: string
format: uri
example:
_profile: 'https://api.apiture.com/schemas/common/abstractRequest/v2.0.0/profile.json'
_links:
self:
href: 'https://api.devbank.apiture.com/applications/'
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/abstractRequest/v2.0.0/model.json'
x-apiture-namespace: common
type: object
x-apiture-flattened: true
links:
title: Links (v1.0.0)
x-apiture-version: 1.0.0
description: |-
An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.
This schema was resolved from [`common/links`](https://production.api.apiture.com/schemas/common/links/v1.0.0/model.json).
type: object
x-apiture-key: linkRelationName
additionalProperties:
$ref: '#/components/schemas/link'
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/links/v1.0.0/model.json'
x-apiture-namespace: common
properties: {}
x-apiture-flattened: true
error:
x-apiture-version: 2.0.0
title: Error (v2.0.0)
description: |-
Describes an error in an API request or in a service called via the API.
This schema was resolved from [`common/error`](https://production.api.apiture.com/schemas/common/error/v2.0.0/model.json).
required:
- message
properties:
message:
type: string
description: A localized message string describing the error condition.
_id:
description: >-
A unique identifier for this error instance. This may be used as a correlation ID with the root cause error (i.e. this ID may be logged at
the source of the error). This is is an opaque string.
readOnly: true
type: string
statusCode:
description: The HTTP status code associate with this error.
type: integer
minimum: 100
maximum: 599
example: 422
type:
type: string
description: >-
An error identifier which indicates the category of error and associate it with API support documentation or which the UI tier can use to
render an appropriate message or hint. This provides a finer level of granularity than the `statusCode`. For example, instead of just 400
Bad Request, the `type` may be much more specific. such as `integerValueNotInAllowedRange` or `numericValueExceedsMaximum` or
`stringValueNotInAllowedSet`.
occurredAt:
type: string
format: date-time
description: 'An [RFC 3339](https://tools.ietf.org/html/rfc3339) UTC time stamp indicating when the error occurred.'
example: '2018-02-02T03:37:15.375Z'
attributes:
description: >-
Informative values or constraints which describe the error. For example, for a value out of range error, the attributes may specify the
`minimum` and `maximum` values. This allows clients to present error messages as they see fit (the API does not assume the
client/presentation tier). The set of attributes varies by error `type`.
allOf:
- $ref: '#/components/schemas/attributes'
remediation:
type: string
description: An optional localized string which provides hints for how the user or client can resolve the error.
errors:
description: An optional array of nested error objects. This property is not always present.
type: array
items:
$ref: '#/components/schemas/error'
_links:
$ref: '#/components/schemas/links'
example:
_id: 2eae46e1575c0a7b0115a4b3
message: Descriptive error message...
statusCode: 422
type: errorType1
remediation: Remediation string...
occurredAt: '2018-01-25T05:50:52.375Z'
errors:
- _id: ccdbe2c5c938a230667b3827
message: An optional embedded error
- _id: dbe9088dcfe2460f229338a3
message: Another optional embedded error
_links:
describedby:
href: 'https://developer.apiture.com/errors/errorType1'
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/error/v2.0.0/model.json'
x-apiture-namespace: common
type: object
x-apiture-flattened: true
attributes:
x-apiture-version: 2.0.0
title: Attributes (v2.0.0)
description: |-
An optional map of name/value pairs which contains additional dynamic data about the resource.
This schema was resolved from [`common/attributes`](https://production.api.apiture.com/schemas/common/attributes/v2.0.0/model.json).
type: object
x-apiture-key: attributeName
additionalProperties:
$ref: '#/components/schemas/attributeValue'
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/attributes/v2.0.0/model.json'
x-apiture-namespace: common
properties: {}
x-apiture-flattened: true
link:
x-apiture-version: 1.0.0
title: Link (v1.0.0)
description: >-
Describes a hypermedia link within a `_links` object in HAL representations. In Apiture APIs, links are [HAL
links](https://developer.apiture.com/docs/concepts/links), but Apiture APIs do not use the `name` or `hreflang` properties of HAL. Apiture
links _may_ include a `method` property.
This schema was resolved from [`common/link`](https://production.api.apiture.com/schemas/common/link/v1.0.0/model.json).
required:
- href
properties:
href:
type: string
format: uri
description: The URI or URI template for the resource/operation this link refers to.
type:
type: string
description: The media type for the resource.
templated:
type: boolean
description: 'If true, the link''s href is a [URI template](https://tools.ietf.org/html/rfc6570).'
title:
type: string
description: An optional human-readable localized title for the link.
deprecation:
type: string
format: uri
description: 'If present, the containing link is deprecated and the value is a URI which provides human-readable text information about the deprecation.'
profile:
type: string
format: uri
description: 'The URI of a profile document, a JSON document which describes the target resource/operation.'
example:
href: 'https://api.devbank.apiture.com/applications/application/328f6bf6-d762-422f-a077-ab91ca4d0b6f'
title: Application
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/link/v1.0.0/model.json'
x-apiture-namespace: common
type: object
x-apiture-flattened: true
attributeValue:
x-apiture-version: 2.0.0
title: Attribute Value (v2.0.0)
description: |-
The data associated with this attribute.
This schema was resolved from [`common/attributeValue`](https://production.api.apiture.com/schemas/common/attributeValue/v2.0.0/model.json).
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/attributeValue/v2.0.0/model.json'
x-apiture-namespace: common
type: object
properties: {}
x-apiture-flattened: true
responses:
'304':
description: Not Modified. The resource has not been modified since it was last fetched.
'400':
description: >-
Bad Request. The request body or one or more of the query parameters was not well formed. The `_error` field in the response will contain
details about the request error.
content:
application/hal+json:
schema:
$ref: '#/components/schemas/errorResponse'
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
'422':
description: >-
Unprocessable Entity. One or more of the query parameters was well formed but otherwise invalid. The `_error` field in the response will
contain details about the request error.
content:
application/hal+json:
schema:
$ref: '#/components/schemas/errorResponse'
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
403Key:
description: |-
Conflict. Cannot create a client application for a user without a valid partner organization.
This error response may have one of the following `type` values:
* [`invalidPartnerDomain`](#err-invalidPartnerDomain)
x-apiture-errors:
- invalidPartnerDomain
content:
application/hal+json:
schema:
$ref: '#/components/schemas/errorResponse'
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
409Key:
description: >-
Conflict. A key cannot be created for the corresponding client application and API environment; an existing key already exists in the
`pending`, `inactive` or `active` state.
content:
application/hal+json:
schema:
$ref: '#/components/schemas/errorResponse'
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
400ActivateKey:
description: |-
Bad Request. The key parameter was malformed or does not refer to an existing or accessible key.
This error response may have one of the following `type` values:
* [`keyRefNotFound`](#err-keyRefNotFound)
x-apiture-errors:
- keyRefNotFound
content:
application/hal+json:
schema:
$ref: '#/components/schemas/errorResponse'
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
409ActivateKeyConflict:
description: >-
Conflict. The request to change the state of the key is not allowed. The `_error` field in the response will contain details about the request
error.
content:
application/hal+json:
schema:
$ref: '#/components/schemas/errorResponse'
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
400DeactivateKey:
description: |-
Bad Request. The key parameter was malformed or does not refer to an existing or accessible key.
This error response may have one of the following `type` values:
* [`keyRefNotFound`](#err-keyRefNotFound)
x-apiture-errors:
- keyRefNotFound
content:
application/hal+json:
schema:
$ref: '#/components/schemas/errorResponse'
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
409DeactivateKeyConflict:
description: >-
Conflict. The request to change the state of the key is not allowed. The `_error` field in the response will contain details about the request
error.
content:
application/hal+json:
schema:
$ref: '#/components/schemas/errorResponse'
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
404Key:
description: >-
Not Found. There is no such key resource at the specified `{keyId}`. The `_error` field in the response will contain details about the request
error.
content:
application/hal+json:
schema:
$ref: '#/components/schemas/errorResponse'
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
204Deleted:
description: No Content. The resource was deleted successfully.
parameters:
environmentQueryParam:
name: environment
description: The target API environment ID or host name where the explorer key is deployed.
in: query
required: true
schema:
type: string
environmentTokenQueryParam:
name: environmentAccessToken
description: >-
The access token which grants the user access to the target environment. The (dev portal) application obtains this token when the user
authenticates against the client environment.
in: query
required: true
schema:
type: string
keyQueryParam:
name: key
required: true
in: query
description: >-
A string which uniquely identifies a key which is to added to the `activeKeys` or `inactiveKeys` resource sets. This may be the unique `keyId`
or the URI of the key.
schema:
type: string
noNotificationQueryParam:
name: noNotification
in: query
required: false
description: >-
If `true`, suppress the notification (typically, email) to the key/application owner or admin that a key has been created or the state of the
API key has changed. If `false` (default), send the notification. Use `?noNotificaton=true` when activating/deacticvating a client application
and the notification for that operation suffices (so the user does not receive too many emails all at once.)
schema:
type: boolean
default: false
keyIdPathParam:
name: keyId
description: The unique identifier of this key. This is an opaque string. This is _not_ the actual API Key; the `API-Key` header is the `key` property.
in: path
required: true
schema:
type: string
startQueryParam:
name: start
in: query
description: >-
Represents the first record of the page of results. This is supplied by the service when paginating items: the `next` link includes a
`?start=` query parameter which refers to beginning of the next page of items.
schema:
type: string
filterQueryParam:
name: filter
in: query
description: 'Optional filter criteria. See [filtering](http://developer.apiture.com/docs/concepts/filtering).'
schema:
type: string
stateQueryParam:
name: state
in: query
description: >-
Subset the resources to only those whose `state` matches the query, such as `?state=active`. The value may be a `|` separated list of states,
such as `?state=pending|active` to match all resources whose `state` is either `pending` _or_ `active`. If `?filter=` is also used, the two
are combined with an implicit `and()` operation.
style: pipeDelimited
schema:
type: array
items:
type: string
enum:
- pending
- active
- inactive
requestBodies:
key:
content:
application/hal+json:
schema:
$ref: '#/components/schemas/key'
application/json:
schema:
$ref: '#/components/schemas/key'
required: true
securitySchemes:
apiKey:
type: apiKey
name: API-Key
in: header
description: >-
API Key based authentication. Each client application must pass its private, unique API key, allocated in the developer portal, via the
`API-Key: {api-key}` request header.
accessToken:
type: oauth2
description: >-
OAuth2 client access token authentication. The client authenticates against the server at `authorizationUrl`, passing the client's private
`clientId` (and optional `clientSecret`) as part of this flow. The client obtains an access token from the server at `tokenUrl`. It then
passes the received access token via the `Authorization: Bearer {access-token}` header in subsequent API calls. The authorization process also
returns a refresh token which the client should use to renew the access token before it expires.
flows:
authorizationCode:
authorizationUrl: 'https://auth.devbank.apiture.com/auth/oauth2/authorize'
tokenUrl: 'https://api.devbank.apiture.com/auth/oauth2/token'
scopes:
data/read: Read access to API keys.
admin/write: Write (update) access to API keys.
data/write: Write (update) access to API keys.
admin/delete: Delete access to API keys.
admin/full: Full access to API keys.