Vault API Definition

The Vault API lets services export or manage secrets in a project. Paths are relative to the API base URL, such as https://cloud.getgitops.com/api.

Authentication

Send a project-scoped API key as a bearer token with every request:

Authorization: Bearer <api-key>

The API key must belong to the requested project and have the permission required by the endpoint. Session authentication is also supported for signed-in users with the same permission.

All paths are normalized: /, /database, and /services/payments are valid. API responses use JSON unless noted otherwise. Validation failures return 400, missing projects, folders, or secrets return 404, and unauthorized requests return 403.

Export secrets

GET /vault/export

Exports every secret in one folder and environment. Requires project:vault:secrets:export.

Query parameter	Required	Description
projectId	Yes	Project UUID.
env	Yes	Environment slug, such as production.
path	No	Folder path. Defaults to /.
format	No	Export format: env or json. Defaults to env.

The response is an attachment with Cache-Control: no-store: text/plain for env or application/json for json.

curl --request GET 
	--header "Authorization: Bearer $GOPS_API_KEY" 
	"https://cloud.getgitops.com/api/vault/export?projectId=$PROJECT_ID&env=production&path=/database&format=env"

Create a secret

POST /vault/secret

Creates a secret in a folder. Requires project:vault:secrets:create.

JSON field	Required	Description
projectId	Yes	Project UUID.
key	Yes	Secret key, such as DATABASE_URL.
path	No	Folder path. Defaults to /. The folder must exist.
description	No	Description of the secret.
values	No	Object mapping environment slugs to secret values.

Returns 201 with { "secret": ... }.

curl --request POST https://cloud.getgitops.com/api/vault/secret 
	--header "Authorization: Bearer $GOPS_API_KEY" 
	--header "Content-Type: application/json" 
	--data '{
		"projectId": "'"$PROJECT_ID"'",
		"path": "/database",
		"key": "DATABASE_URL",
		"description": "Primary database connection",
		"values": { "production": "postgres://..." }
	}'

Read a secret

GET /vault/secret/:key

Returns a secret by key and folder. Requires project:vault:secrets:read.

Query parameter	Required	Description
projectId	Yes	Project UUID.
path	No	Folder path. Defaults to /.

Returns 200 with { "secret": ... } or 404 when the key is not present in that folder.

curl --request GET 
	--header "Authorization: Bearer $GOPS_API_KEY" 
	"https://cloud.getgitops.com/api/vault/secret/DATABASE_URL?projectId=$PROJECT_ID&path=/database"

Update a secret

PATCH /vault/secret/:key

Sets a secret value for one environment. The secret key and folder cannot be changed. Requires project:vault:secrets:update.

Query parameter	Required	Description
projectId	Yes	Project UUID.
path	No	Folder path. Defaults to /.

JSON field	Required	Description
environment	Yes	Environment slug whose value changes.
value	Yes	New secret value.
description	No	Replacement secret description.

Returns 200 with { "secret": ... }; the returned secret includes the updated value but does not expose all environment values.

curl --request PATCH "https://cloud.getgitops.com/api/vault/secret/DATABASE_URL?projectId=$PROJECT_ID&path=/database" 
	--header "Authorization: Bearer $GOPS_API_KEY" 
	--header "Content-Type: application/json" 
	--data '{ "environment": "production", "value": "postgres://..." }'

Delete a secret

DELETE /vault/secret/:key

Deletes a secret by key from a folder. Requires project:vault:secrets:delete.

Query parameter	Required	Description
projectId	Yes	Project UUID.
path	No	Folder path. Defaults to /.

Returns 200 with { "success": true }.

curl --request DELETE 
	--header "Authorization: Bearer $GOPS_API_KEY" 
	"https://cloud.getgitops.com/api/vault/secret/DATABASE_URL?projectId=$PROJECT_ID&path=/database"