Humanitec ResourceAccount API
ResourceAccount represents the account being used to access a resource. Resource Accounts hold credentials that are required to provision and manage resources.
OpenAPI Specification
openapi: 3.0.0
info:
title: Humanitec AccountType ResourceAccount API
version: 0.28.24
description: '# Introduction
The *Humanitec API* allows you to automate and integrate Humanitec into your developer and operational workflows.
The API is a REST based API. It is based around a set of concepts:
* Core
* External Resources
* Sets and Deltas
## Authentication
Almost all requests made to the Humanitec API require Authentication. See our [Developer Docs on API Authentication](https://developer.humanitec.com/platform-orchestrator/reference/api-references/#authentication) for instructions.
## Content Types
The Humanitec API, unless explicitly specified, only accepts content types of `application/json` and will always return valid `application/json` or an empty response.
## Response Codes
### Success
Any response code in the `2xx` range should be regarded as success.
| **Code** | **Meaning** |
|----------|-------------------------------------|
| `200` | Success |
| `201` | Success, a new resource was created |
| `204` | Success, but no content in response |
_Note: We plan to simplify the interface by replacing 201 with 200 status codes._
### Failure
Any response code in the `4xx` range should be regarded as an error that can be rectified by the client. `5xx` error codes indicate errors that cannot be corrected by the client.
| **Code** | **Meaning** |
|----------|-----------------------------------------------------------------------------------------------------------------------|
| `400` | General error. (Body will contain details) |
| `401` | Attempt to access protected resource without `Authorization` Header. |
| `403` | The `Bearer` or `JWT` does not grant access to the requested resource. |
| `404` | Resource not found. |
| `405` | Method not allowed |
| `409` | Conflict. Usually indicated a resource with that ID already exists. |
| `422` | Unprocessable Entity. The body was not valid JSON, was empty or contained an object different from what was expected. |
| `429` | Too many requests - request rate limit has been reached. |
| `500` | Internal Error. If it occurs repeatedly, contact support. |
'
contact:
name: Humanitec Support
email: support@humanitec.com
x-logo:
url: humanitec-logo.png
altText: Humanitec logo
servers:
- url: https://api.humanitec.io/
tags:
- name: ResourceAccount
x-displayName: Resource Accounts
description: 'ResourceAccount represents the account being used to access a resource.
Resource Accounts hold credentials that are required to provision and manage resources.
<SchemaDefinition schemaRef="#/components/schemas/ResourceAccountResponse" />
'
paths:
/orgs/{orgId}/resources/accounts:
get:
tags:
- ResourceAccount
summary: List Resource Accounts in the organization.
operationId: listResourceAccounts
parameters:
- name: orgId
in: path
description: 'The Organization ID.
'
required: true
schema:
type: string
responses:
'200':
description: 'A possibly empty list of Resources Accounts.
'
content:
application/json:
schema:
items:
$ref: '#/components/schemas/ResourceAccountResponse'
type: array
'500':
description: 'Internal application error.
'
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
post:
tags:
- ResourceAccount
summary: Create a new Resource Account in the organization.
operationId: createResourceAccount
parameters:
- name: orgId
in: path
description: The Organization ID.
required: true
schema:
type: string
- name: dry_run
in: query
description: Validate the request but do not persist the change.
example: true
schema:
type: boolean
- name: check_credential
in: query
description: Validate that the Account credential authenticates successfully.
example: true
schema:
type: boolean
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateResourceAccountRequestRequest'
responses:
'200':
description: 'The newly created Resources Account details.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceAccountResponse'
'204':
description: The Resource Account details are valid but were not persisted because dry-run is enabled.
'400':
description: 'One or more request parameters is missing or invalid.
'
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
'401':
description: 'Authentication token is missing or invalid.
'
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
'409':
description: 'A Resources Account already exists.
'
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
'500':
description: 'Internal application error.
'
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
/orgs/{orgId}/resources/accounts/{accId}:
get:
tags:
- ResourceAccount
summary: Get a Resource Account.
operationId: getResourceAccount
parameters:
- name: orgId
in: path
description: 'The Organization ID.
'
required: true
schema:
type: string
- name: accId
in: path
description: 'The Resource Account ID.
'
required: true
schema:
type: string
responses:
'200':
description: 'The requested Resources Account.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceAccountResponse'
'404':
description: 'A Resource Account with the ''accId'' ID is not found or does not belong to the organization.
'
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
'500':
description: 'Internal application error.
'
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
delete:
tags:
- ResourceAccount
summary: Delete an unused Resource Account.
description: 'A Resource Account can be deleted if it is not referenced or referenced only by deleted Resource Definitions.
Resource Definition Versions which reference the deleted Resource Account cannot be used in deployments.
'
operationId: deleteResourceAccount
parameters:
- name: orgId
in: path
description: 'The Organization ID.
'
required: true
schema:
type: string
- name: accId
in: path
description: 'The Resource Account ID.
'
required: true
schema:
type: string
responses:
'204':
description: 'The account was successfully deleted.
'
'400':
description: 'The Resource Account cannot be deleted as at least one non-deleted Resource Definition or one Active Resource still referencing it.
In the error the coordinates of the referencing resources are provided.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ConflictingResourcesErrorResponse'
'404':
description: 'A Resource Account with the ''accId'' ID is not found or does not belong to the organization.
'
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
'500':
description: 'Internal application error.
'
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
patch:
tags:
- ResourceAccount
summary: Update a Resource Account.
operationId: patchResourceAccount
parameters:
- name: orgId
in: path
description: 'The Organization ID.
'
required: true
schema:
type: string
- name: accId
in: path
description: 'The Resource Account ID.
'
required: true
schema:
type: string
- name: dry_run
in: query
description: Validate the request but do not persist the change.
example: true
schema:
type: boolean
- name: check_credential
in: query
description: Validate that the Account credential authenticates successfully.
example: true
schema:
type: boolean
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateResourceAccountRequestRequest'
responses:
'200':
description: 'The updated Resource Account details.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceAccountResponse'
'204':
description: The Resource Account details are valid but were not persisted because dry-run is enabled.
'400':
description: 'One or more request parameters is missing or invalid.
'
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
'404':
description: 'A Resource Account with the ''accId'' ID is not found or does not belong to the organization.
'
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
'500':
description: 'Internal application error.
'
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
/orgs/{orgId}/resources/accounts/{accId}/actions/check:
post:
tags:
- ResourceAccount
summary: Check the credentials of an existing Resource Account
description: Check the validity of a Resource Account and return any problems that may cause it to not work as expected.
operationId: checkResourceAccount
parameters:
- name: orgId
in: path
description: The Organization ID.
required: true
schema:
type: string
- name: accId
in: path
description: The Resource Account ID.
required: true
schema:
type: string
responses:
'200':
description: The updated Account Type.
content:
application/json:
schema:
$ref: '#/components/schemas/CheckResourceAccountData'
'400':
description: The Resource Account is not valid or could not be validated.
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
components:
schemas:
ActiveResourceResponse:
description: 'Active Resources represent the concrete resources provisioned for an Environment. They are provisioned on the first deployment after a dependency on a particular resource type is introduced into an Environment. In general, Active Resources are only deleted when their introductory Environment is deleted.
Active Resources are provisioned based on a Resource Definition. The Resource Definition describes how to provision a concrete resource based on a Resource Type and metadata about the Environment (for example the Environment Type or the Application ID). The criteria for how to choose a Resource Definition is known as a Matching Criteria. If the Matching Criteria changes or the Resource Definition is deleted, the concrete resource represented by an Active Resource might be deleted and reprovisioned when a deployment occurs in the Environment.'
example:
app_id: test-app
class: default
def_id: gcp-dev-postgres
def_version_id: 01234567-89ab-cdef-0123-4567890abcdef
deploy_id: 172a1013b
env_id: gcp-dev
env_type: development
gu_res_id: 7bd3966c9ff8eaa66c5cce855c03d715857c3440
org_id: test-org
res_id: modules.my-module.externals.my-db
resource:
host: 127.0.0.1
name: db_33c7ef9b_8d90-4c62_a1cf_0cdd30fd29a9
port: 5432
secret_refs:
credentials: orgs/test-org/resources/7bd3966c9ff8eaa66c5cce855c03d715857c3440/secrets/.credentials
type: postgres
updated_at: '2020-06-23T16:53:12Z'
properties:
app_id:
description: The ID of the App the resource is associated with.
type: string
class:
description: The Resource Class of the resource
type: string
criteria_id:
description: The Matching Criteria ID.
type: string
def_id:
description: The Resource Definition that this resource was provisioned from.
type: string
def_version_id:
description: The Resource Definition Version that this resource was provisioned from.
type: string
target_def_version_id:
description: The Resource Definition Version pinned to this resource to be provisioned from.
type: string
deploy_id:
description: The deployment that the resource was last provisioned in.
type: string
driver_account:
description: (Optional) Security account required by the driver.
type: string
driver_type:
description: The driver to be used to create the resource.
type: string
env_id:
description: The ID of the Environment the resource is associated with.
type: string
env_type:
description: The Environment Type of the Environment specified by env_id.
type: string
gu_res_id:
description: Globally unique resource id
type: string
org_id:
description: the ID of the Organization the Active Resource is associated with.
type: string
res_id:
description: The ID of the resource
type: string
resource:
additionalProperties: true
description: The resource provisioning outputs ('values' only).
type: object
scheduled_deletion:
description: Deletion is scheduled for this resource.
type: boolean
secret_refs:
additionalProperties: true
description: Secret references from the resource provisioning output.
type: object
status:
description: 'Current resource status: ''pending'', ''active'', or ''deleting''.'
type: string
type:
description: The Resource Type of the resource
type: string
updated_at:
description: The time the resource was last provisioned as part of a deployment.
example: '2020-06-22T09:37:23.523Z'
type: string
format: date-time
required:
- org_id
- app_id
- env_id
- env_type
- res_id
- def_id
- def_version_id
- type
- driver_type
- class
- status
- resource
- secret_refs
- updated_at
- deploy_id
- gu_res_id
- scheduled_deletion
type: object
CheckResourceAccountField:
description: An identity field or property resulting from the account check.
type: object
properties:
id:
type: string
description:
type: string
value:
type: string
additionalProperties: false
required:
- id
- description
- value
ConflictingResourcesErrorResponse:
description: 'Represents a standard Humanitec Error with additional details which describe why an action on a specific resource cannot be performed due to some other entities linked to it.
'
properties:
details:
$ref: '#/components/schemas/ConflictingResourcesErrorResponseDetails'
error:
type: string
message:
type: string
required:
- error
- message
- details
type: object
ResourceDefinitionResponse:
description: 'A Resource Definitions describes how and when a resource should be provisioned. It links a driver (the how) along with a Matching Criteria (the when) to a Resource Type. This allows Humanitec to invoke a particular driver for the required Resource Type in the context of a particular Application and Environment.
The schema for the `driver_inputs` is defined by the `input_schema` property on the DriverDefinition identified by the `driver_type` property.'
example:
created_at: '2020-05-23T12:32:16Z'
created_by: a.user@example.com
criteria:
- env_type: development
id: '123456'
driver_account: gcp-dev-cloudsql
driver_inputs:
secret_refs:
credentials:
password:
value: <secret>
user:
ref: vault/path/to/data/secrets/user
store: my-external-vault
version: '1'
values:
instance: my-dev-project:my-region:dev-db
driver_type: humanitec/postgres-cloudsql
id: dev-postgres
is_default: false
is_deleted: false
name: Dev Postgres Instance
org_id: test-org
provision:
aws-policy:
is_dependent: false
match_dependents: false
dns#my-dns: {}
type: postgres
properties:
created_at:
description: The timestamp of when this record has been created.
example: '2020-06-22T09:37:23.523Z'
title: Simplified extended ISO format date/time string.
type: string
format: date-time
created_by:
description: The user who created this record.
type: string
updated_at:
description: The timestamp of when this record has been updated.
example: '2020-06-22T09:37:23.523Z'
title: Simplified extended ISO format date/time string.
type: string
format: date-time
updated_by:
description: The user who updated this record.
type: string
criteria:
description: (Optional) The criteria to use when looking for a Resource Definition during the deployment.
items:
$ref: '#/components/schemas/MatchingCriteriaResponse'
type: array
driver_account:
description: (Optional) Security account required by the driver.
type: string
driver_inputs:
$ref: '#/components/schemas/ValuesSecretsRefsResponse'
description: (Optional) Additional input data to be passed to the driver.
driver_type:
description: The driver to be used to create the resource.
type: string
id:
description: The Resource Definition ID.
type: string
active_version_id:
description: The active Resource Definition Version ID.
type: string
is_default:
description: Indicates this definition is a built-in one (provided by Humanitec).
type: boolean
is_deleted:
description: Indicates if this record has been marked for deletion. The Resource Definition that has been marked for deletion cannot be used to provision new resources.
type: boolean
name:
description: The display name.
type: string
org_id:
description: The Organization ID.
type: string
provision:
additionalProperties:
$ref: '#/components/schemas/ProvisionDependenciesResponse'
description: (Optional) A map where the keys are resType#resId (if resId is omitted, the same id of the current resource definition is used) of the resources that should be provisioned when the current resource is provisioned. This also specifies if the resources have a dependency on the current resource.
type: object
type:
description: The Resource Type.
type: string
required:
- org_id
- id
- name
- type
- created_at
- created_by
- is_default
- is_deleted
- driver_type
- active_version_id
type: object
HumanitecErrorResponse:
description: HumanitecError represents a standard Humanitec Error
properties:
details:
additionalProperties: true
type: object
description: (Optional) Additional information is enclosed here.
error:
type: string
example: API-000
description: A short code to help with error identification.
message:
type: string
example: Could not validate token
description: A Human readable message about the error.
required:
- error
- message
type: object
example:
error: API-000
message: Could not validate token.
ProvisionDependenciesResponse:
description: ProvisionDependencies defines resources which are needed to be co-provisioned with the current resource.
properties:
is_dependent:
description: If the co-provisioned resource is dependendent on the current one.
type: boolean
match_dependents:
description: If the resources dependant on the main resource, are also dependant on the co-provisioned one.
type: boolean
params:
additionalProperties: true
description: (Optional) Additional parameters to be passed to the driver which will provision the resource.
type: object
required:
- is_dependent
type: object
ConflictingResourcesErrorResponseDetailsResources:
type: object
properties:
resource_definitions:
description: List of non-deleted Resource Definitions referencing the specified Resource Account.
type: array
items:
$ref: '#/components/schemas/ResourceDefinitionResponse'
active_resources:
description: List of Active Resources referencing the specified Resource Account.
type: array
items:
$ref: '#/components/schemas/ActiveResourceResponse'
additionalProperties: false
CheckResourceAccountData:
description: The successful check response details.
type: object
properties:
identity_fields:
description: A set of identity fields and properties resulting from the account check.
type: array
items:
$ref: '#/components/schemas/CheckResourceAccountField'
warnings:
description: A list of warnings related to this account.
type: array
items:
type: string
additionalProperties: false
required:
- identity_fields
CreateResourceAccountRequestRequest:
description: CreateResourceAccountRequest describes the request to create a new security account.
example:
credentials:
password: '***'
username: '***'
id: gcp-dev-postgres
name: GCP Dev Postgres
type: gcp-service-account
properties:
credentials:
additionalProperties: true
description: Credentials associated with the account.
type: object
id:
description: Unique identifier for the account (in scope of the organization it belongs to).
type: string
name:
description: Display name.
type: string
type:
description: The type of the account
type: string
type: object
required:
- id
- type
- name
- credentials
MatchingCriteriaResponse:
description: 'Matching Criteria are a set of rules used to choose which Resource Definition to use to provision a particular Resource Type.
Matching criteria are made up in order of specificity with least specific first:
- Environment Type (`env_type`)
- Application (`app_id`)
- Environment (`env_id`)
- Resource (`res_id`)
When selecting matching criteria, the most specific one is selected. In general, this means of all the Matching Criteria fully matching the context, the Matching Criteria Rule with the most specific element filled is chosen. If there is a tie, the next most specific elements are compared and so on until one is chosen.
**NOTE:**
Humanitec will reject the registration of matching criteria rules that duplicate rules already present for a Resource Type.'
properties:
app_id:
description: (Optional) The ID of the Application that the Resources should belong to.
type: string
class:
description: (Optional) The class of the Resource in the Deployment Set. Can not be empty, if is not defined, set to `default`.
type: string
env_id:
description: (Optional) The ID of the Environment that the Resources should belong to. If `env_type` is also set, it must match the Type of the Environment for the Criteria to match.
type: string
env_type:
description: (Optional) The Type of the Environment that the Resources should belong to. If `env_id` is also set, it must have an Environment Type that matches this parameter for the Criteria to match.
type: string
id:
description: Matching Criteria ID
type: string
res_id:
description: (Optional) The ID of the Resource in the Deployment Set. The ID is normally a `.` separated path to the definition in the set, e.g. `modules.my-module.externals.my-database`.
type: string
required:
- class
- id
type: object
UpdateResourceAccountRequestRequest:
description: UpdateResourceAccountRequest describes the request to update the security account details.
example:
credentials:
password: '***'
username: '***'
name: GCP Dev Postgres
properties:
credentials:
additionalProperties: true
description: Credentials associated with the account.
type: object
name:
description: Display name.
type: string
type: object
ValuesSecretsRefsResponse:
description: ValuesSecretsRefs stores data that should be passed around split by sensitivity.
example:
secret_refs:
credentials:
password:
value: <secret>
user:
ref: vault/path/to/data/secrets/user
store: my-external-vault
version: '1'
secrets:
password: vault/path/to/data/.secrets/password
user: vault/path/to/data/.secrets/user
values:
host: 127.0.0.1
name: my-database
properties:
secret_refs:
additionalProperties: true
description: 'Secrets section of the data set. They can hold sensitive information that will be stored in the primary organization secret store and replaced with the secret store paths when sent outside, or secret references stored in a defined secret store. Can''t be used together with `secrets`.
They can hold a nested structure but leaf objects need to be of type SecretReference, where:
- `store` is a Secret Store id. It can''t be `humanitec`. It''s mandatory if `ref` is defined and can''t be used in request payloads if `value` is defined.
- `ref` is the secret key in the format of the target store. It can''t be used in request payloads if `value` is defined.
- `version` is the version of the secret as defined in the target store. It can be defined only if `ref` is defined.
- `value` is the value to store in the organizations primary secret store. It can''t be used in request payloads if `ref` is defined.'
type: object
secrets:
additionalProperties: true
description: Secrets section of the data set. Sensitive information is stored in the primary organization secret store and replaced with the secret store paths when sent outside. Can't be used together with `secret_refs`.
type: object
values:
additionalProperties: true
description: Values section of the data set. Passed around as-is.
type: object
type: object
ResourceAccountResponse:
description: 'ResourceAccount represents the account being used to access a resource.
Resource Accounts hold credentials that are required to provision and manage resources.'
example:
created_at: '2020-05-22T14:58:07Z'
created_by: test-user
id: gcp-dev-postgres
is_default: false
is_used: true
name: GCP Dev Postgres
type: gcp
properties:
created_at:
description: The timestamp of when the account was created.
example: '2020-06-22T09:37:23.523Z'
format: date-time
title: Simplified extended ISO format date/time string.
type: string
created_by:
description: The ID of the user who created the account.
type: string
id:
description: Unique identifier for the account (in scope of the organization it belongs to).
type: string
is_used:
description: Indicates if this account is being used (referenced) by any resource definition or active resource.
type: boolean
name:
description: Display name.
type: string
type:
description: The type of the account
type: string
required:
- id
- name
- type
- is_used
- created_by
- created_at
type: object
ConflictingResourcesErrorResponseDetails:
description: Object composed by the list of resources which prevent the deletion of the specified entity. The resources are indexed by their kind.
type: object
properties:
referencing_resources:
$ref: '#/components/schemas/ConflictingResourcesErrorResponseDetailsResources'
required:
- referencing_resources
additionalProperties: false
externalDocs:
description: Find out more about how to use Humanitec in your every-day development work.
url: https://developer
# --- truncated at 32 KB (32 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/humanitec/refs/heads/main/openapi/humanitec-resourceaccount-api-openapi.yml