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. Response and request bodies using this createKey schema may contain the following links:
RelSummaryMethod
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. Response and request bodies using this key schema may contain the following links:
RelSummaryMethod
apiture:activateActivate a keyPOST
apiture:deactivateDeactivate a keyPOST
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):
ValueDescription
pendingPending: A key that has been requested but not activated (not approved).
activeActive: A key that has been approved and is active.
inactiveInactive: 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):
ValueDescription
discovererDiscoverer 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.
explorerExplorer 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.
partnerPartner 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.
productionProduction Key: Production keys are partner keys that are attached to a production (non-test, non-development) environment.
privatePrivate 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. Response and request bodies using this sampleDataRequest schema may contain the following links:
RelSummaryMethod
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.