Humanitec SecretStore API
Secret Store represents external secret management system used by an organization to store secrets referenced in Humanitec.
OpenAPI Specification
openapi: 3.0.0
info:
title: Humanitec AccountType SecretStore 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: SecretStore
x-displayName: Secret Store
description: 'Secret Store represents external secret management system used by an organization to store secrets referenced in Humanitec.
<SchemaDefinition schemaRef="#/components/schemas/SecretStoreRequest" />
'
paths:
/orgs/{orgId}/secretstores:
get:
tags:
- SecretStore
summary: Get list of Secret Stores for the given organization.
parameters:
- name: orgId
in: path
description: 'The Organization ID.
'
required: true
schema:
type: string
responses:
'200':
description: 'List of Secret Stores.
'
content:
application/json:
schema:
items:
$ref: '#/components/schemas/SecretStoreResponse'
type: array
post:
tags:
- SecretStore
summary: Create a Secret Store for the given organization.
parameters:
- name: orgId
in: path
description: 'The Organization ID.
'
required: true
schema:
type: string
requestBody:
description: 'Secret Store data.
'
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateSecretStorePayloadRequest'
responses:
'201':
description: 'Secret Store successfully added.
'
content:
application/json:
schema:
$ref: '#/components/schemas/SecretStoreResponse'
'400':
description: 'One or more request body parameters are either missing, invalid, or the requested payload is not provided or is malformed.
'
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
'401':
description: 'Request unauthorised.
'
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
'409':
description: 'Conflict.
'
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
/orgs/{orgId}/secretstores/{storeId}:
get:
tags:
- SecretStore
summary: Get the Secret Store.
parameters:
- name: orgId
in: path
description: 'The Organization ID.
'
required: true
schema:
type: string
- name: storeId
in: path
description: 'The Secret Store ID.
'
required: true
schema:
type: string
responses:
'200':
description: 'Returns Secret Stores.
'
content:
application/json:
schema:
$ref: '#/components/schemas/SecretStoreResponse'
'404':
description: 'Secret Store not found.
'
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
delete:
tags:
- SecretStore
summary: Delete the Secret Store.
parameters:
- name: orgId
in: path
description: 'The Organization ID.
'
required: true
schema:
type: string
- name: storeId
in: path
description: 'The Secret Store ID.
'
required: true
schema:
type: string
responses:
'204':
description: 'Secret Store successfully deleted.
'
'404':
description: 'Secret Store not found.
'
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
patch:
tags:
- SecretStore
summary: Update the Secret Store.
parameters:
- name: orgId
in: path
description: 'The Organization ID.
'
required: true
schema:
type: string
- name: storeId
in: path
description: 'The Secret Store ID.
'
required: true
schema:
type: string
requestBody:
description: 'Secret Store data.
'
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateSecretStorePayloadRequest'
responses:
'200':
description: 'Secret Store successfully updated.
'
content:
application/json:
schema:
$ref: '#/components/schemas/SecretStoreResponse'
'400':
description: 'One or more request body parameters are either missing, invalid, or the requested payload is not provided or is malformed.
'
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
'404':
description: 'Secret Store not found.
'
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
components:
schemas:
GCPAuthRequest:
description: Credentials to authenticate GCP Secret Manager.
properties:
secret_access_key:
type: string
type: object
VaultAuthRequest:
description: Credentials to authenticate Vault.
properties:
role:
type: string
token:
type: string
type: object
AzureKVRequest:
description: Azure Key Vault specification.
properties:
auth:
$ref: '#/components/schemas/AzureAuthRequest'
tenant_id:
type: string
url:
type: string
type: object
AWSSMRequest:
description: AWS Secret Manager specification.
properties:
auth:
$ref: '#/components/schemas/AWSAuthRequest'
endpoint:
type: string
region:
type: string
type: object
AWSAuthRequest:
description: Credentials to authenticate AWS Secret Manager.
properties:
access_key_id:
type: string
secret_access_key:
type: string
type: object
SecretStoreResponse:
description: Secret Store represents external secret management system used by an organization to store secrets referenced in Humanitec.
properties:
awssm:
$ref: '#/components/schemas/AWSSMResponse'
azurekv:
$ref: '#/components/schemas/AzureKVResponse'
created_at:
example: '2020-06-22T09:37:23.523Z'
pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\.[0-9]{3})?Z$
title: Simplified extended ISO format date/time string.
type: string
created_by:
type: string
gcpsm:
$ref: '#/components/schemas/GCPSMResponse'
humanitec:
$ref: '#/components/schemas/HumanitecResponse'
id:
type: string
primary:
type: boolean
updated_at:
example: '2020-06-22T09:37:23.523Z'
pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\.[0-9]{3})?Z$
title: Simplified extended ISO format date/time string.
type: string
updated_by:
type: string
vault:
$ref: '#/components/schemas/VaultResponse'
required:
- id
- primary
- created_at
- created_by
- updated_at
- updated_by
type: object
HumanitecResponse:
description: Humanitec built-in Secret Store specification.
properties: {}
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.
AzureAuthRequest:
description: Credentials to authenticate Azure Key Vault.
properties:
client_id:
type: string
client_secret:
type: string
type: object
CreateSecretStorePayloadRequest:
description: 'Secret Store represents external secret management system used by an organization to store secrets referenced in Humanitec. It must contain exactly one of the following elements to define Secret Store specification: `awssm` (AWS Secret Manager), `azurekv` (Azure Key Vault), `gcpsm` (GCP Secret Manager), `vault` (HashiCorp Vault).'
example:
awssm:
auth:
access_key_id: '...'
secret_access_key: '...'
region: us-east-1
id: my-aws-secret-manager
primary: true
properties:
awssm:
$ref: '#/components/schemas/AWSSMRequest'
description: AWS Secret Manager specification.
azurekv:
$ref: '#/components/schemas/AzureKVRequest'
description: Azure Key Vault specification.
gcpsm:
$ref: '#/components/schemas/GCPSMRequest'
description: GCP Secret Manager specification.
id:
description: The Secret Store ID.
pattern: ^[a-z0-9](?:-?[a-z0-9]+)+$
type: string
primary:
description: Defines whether the Secret Store is the primary secret management system for the organization.
type: boolean
vault:
$ref: '#/components/schemas/VaultRequest'
description: Vault specification.
required:
- id
- primary
type: object
GCPSMRequest:
description: GCP Secret Manager specification.
properties:
auth:
$ref: '#/components/schemas/GCPAuthRequest'
project_id:
type: string
type: object
VaultResponse:
description: Vault specification.
properties:
agent_id:
type: string
path:
type: string
url:
type: string
type: object
AWSSMResponse:
description: AWS Secret Manager specification.
properties:
endpoint:
type: string
region:
type: string
type: object
GCPSMResponse:
description: GCP Secret Manager specification.
properties:
project_id:
type: string
type: object
AzureKVResponse:
description: Azure Key Vault specification.
properties:
tenant_id:
type: string
url:
type: string
type: object
VaultRequest:
description: Vault specification.
properties:
agent_id:
type: string
auth:
$ref: '#/components/schemas/VaultAuthRequest'
path:
type: string
url:
type: string
type: object
UpdateSecretStorePayloadRequest:
description: Secret Store represents external secret management system used by an organization to store secrets referenced in Humanitec.
example:
awssm:
auth:
secret_access_key: s0mE_te$t_wrIte_kee
region: us-east-1
primary: true
properties:
awssm:
$ref: '#/components/schemas/AWSSMRequest'
description: AWS Secret Manager specification.
azurekv:
$ref: '#/components/schemas/AzureKVRequest'
description: Azure Key Vault specification.
gcpsm:
$ref: '#/components/schemas/GCPSMRequest'
description: GCP Secret Manager specification.
primary:
description: Defines whether the Secret Store is the primary secret management system for the organization.
nullable: true
type: boolean
vault:
$ref: '#/components/schemas/VaultRequest'
description: Vault specification.
type: object
externalDocs:
description: Find out more about how to use Humanitec in your every-day development work.
url: https://developer.humanitec.com/
x-tagGroups:
- name: Core
tags:
- Agents
- Application
- Artefact
- ArtefactVersion
- AuditLogs
- Logs
- Deployment
- EnvironmentType
- Environment
- Image
- PublicKeys
- Organization
- Registry
- RuntimeInfo
- SecretStore
- Value
- ValueSetVersion
- name: App Configuration
tags:
- Delta
- Set
- WorkloadProfile
- name: Resources
tags:
- ActiveResource
- DriverDefinition
- MatchingCriteria
- ResourceDefinition
- ResourceDefinitionVersion
- ResourceProvision
- AccountType
- ResourceAccount
- ResourceType
- ResourceClass
- name: Automation
tags:
- AutomationRule
- Event
- Pipelines
- PipelineRuns
- PipelineApprovals
- name: Users
tags:
- UserProfile
- UserRole
- Group
- TokenInfo