Secrets Service API

API Endpoint

http://secrets.agilestacks.com/api/v1

Secrets Service has protected HTTP API to provide access to all it’s functions, such as:

saving and retrieving secrets;
obtaining expiring tokens to access cloud accounts;
manage secrets permissions.

Please read design first.

There are several types of supported entities: cloud-accounts, environments, templates, instances, applications, licenses, and service-accounts.

Supported types of kind field in secret object are: password, cloudAccount, cloudAccessKeys, privateKey, certificate, sshKey, usernamePassword, text, license, token, bearerToken, accessToken, refreshToken, and loginToken.

For kind = 'cloudAccount', Secrets Service will check secret object cloud field is one of: aws, azure, gcp.

For cloud = 'aws' Secret Service additionally accept region and sts AWS endpoint in https://sts(.region).amazonaws.com format.

Resource Group ¶

Secret ¶

GET http://secrets.agilestacks.com/api/v1/secrets/environments/123/02a669c0-543b-432f-a11d-fb21f29c7200

Requestsexample 1

Headers

X-Secrets-Token: user-token

Responses200404403502504

Headers

Content-Type: application/json; charset=utf-8

Body

{
  "id": "02a669c0-543b-432f-a11d-fb21f29c7200",
  "name": "component.postgresql.password",
  "kind": "password",
  "username": "automation-hub",
  "password": "jai0eite3X"
}

This response has no content.

Retrieve Secret
GET`/secrets/{entityKind}/{entityId}/{secretId}`

Reading cloud account entity returns original security-sensitive information masked. The only way to use cloud account is to request session keys via /session-keys.

Password:

{
    "id": "02a669c0-543b-432f-a11d-fb21f29c7200",
    "name": "component.postgresql.password",
    "kind": "usernamePassword",
    "username": "automation-hub",
    "password": "jai0eite3X"
}

Cloud account entity:

{
    "id": "4ae21e5e-c49f-4222-b164-ffb03d8448dd",
    "name": "My AWS",
    "kind": "cloudAccount",
    "cloud": "aws",
    "accessKey": "AKIA****************",
    "secretKey": "IqCFm0**********************************"
}

{
    "id": "4ae21e5e-c49f-4222-b164-ffb03d8448dd",
    "name": "My AWS",
    "kind": "cloudAccount",
    "cloud": "aws",
    "roleArn": "arn:aws:iam::973998981304:role/xaccount-*********************",
    "externalId": "4f60642506******************************",
    "duration": 7200
}

URI Parameters

HideShow

entityKind: string (required) Example: environments
Entity type identifier
entityId: string (required) Example: 123
ID of the Entity
secretId: string (required) Example: 02a669c0-543b-432f-a11d-fb21f29c7200
ID of the Secret

POST http://secrets.agilestacks.com/api/v1/secrets/cloud-accounts/123/02a669c0-543b-432f-a11d-fb21f29c7200/session-keys

Requestsexample 1

Headers

X-Secrets-Token: user-token

Body

{
  "purpose": "stack-k8s-aws deployment",
  "duration": 4800
}

Responses200404403405504502

Headers

Content-Type: application/json; charset=utf-8

Body

{
  "cloud": "aws",
  "accessKey": "AKIA****************",
  "secretKey": "IqCFm0**********************************",
  "sessionToken": "...",
  "ttl": 7200,
  "_env": {
    "AWS_ACCESS_KEY_ID": "...",
    "AWS_SECRET_ACCESS_KEY": "...",
    "AWS_SESSION_TOKEN": "..."
  }
}

This response has no content.

Headers

Content-Type: application/json; charset=utf-8

Body

"errors": [
        {
            "type": "badRequest",
            "detail": "The requested secret is not `cloudAccount` kind",
            "meta": {
                "errors": {
                    "type": "badRequest",
                    "detail": "The requested secret is not `cloudAccount` kind",
                    "meta": {
                        "stack":"Error: The requested secret is not `cloudAccount` kind...js:76:19)"
                    }
                }
            }
        }
    ]
}

This response has no content.

Headers

Content-Type: application/json; charset=utf-8

Body

"errors": [
        {
            "type": "serverError",
            "detail": "AWS STS error: ...",
            "meta": {
                "errors": {
                    "type": "serverError",
                    "detail": "AWS STS error: ...",
                    "meta": {
                        "stack":"Error: AWS STS error: ......js:76:19)"
                    }
                }
            }
        }
    ]
}

Retrieve Cloud Account Session
POST`/secrets/cloud-accounts/{cloudAccountId}/{secretId}/session-keys`

Post to cloud account session endpoint returns cloud-specific credentials to access cloud account.

For AWS a set of temporary security credentials are issued. The keys are valid for duration of the request or of the secret, or the STS default of 1 hour. Optionally, send purpose to be included as part of role session name sent to STS. Optionally, set region and sts (endpoint).

For Azure and GCP as set of static credentials are returned.

If AWS cloud account credentials are accessKey and secretKey pair, then is must be keys either of account root user or IAM user with MFA disabled. The session keys obtained cannot call IAM API due to restriction imposed by AWS, from STS GetSessionToken:

The temporary security credentials created by GetSessionToken can be used to make API calls to any AWS service with the following exceptions:

You cannot call any IAM APIs unless MFA authentication information is included in the request.

You cannot call any STS API except AssumeRole or GetCallerIdentity.

Response object _env: {} field includes cloud-specific set of OS environment variable that should be exported to get cloud CLIs and SDKs working with the cloud account. Additionally, _envAsFiles: [] array indicates which _env keys cannot be presented inline, but must be saved into file for native auth mechanism to pick-up the settings, for example "_envAsFiles": ["GOOGLE_APPLICATION_CREDENTIALS"], "_envAsFiles": ["AZURE_CERTIFICATE_PATH"].

URI Parameters

HideShow

cloudAccountId: string (required) Example: 123
ID of the Cloud Account
secretId: string (required) Example: 02a669c0-543b-432f-a11d-fb21f29c7200
ID of the Secret

POST http://secrets.agilestacks.com/api/v1/secrets/cloud-accounts/123/02a669c0-543b-432f-a11d-fb21f29c7200/session-keys/via/cloud-accounts/456/4676a1a6-dd9c-4f86-b4fc-9c049c0674e7

Requestsexample 1

Headers

X-Secrets-Token: user-token
X-Via-Secrets-Token: via-user-token

Body

{}

Responses200

Headers

Content-Type: application/json; charset=utf-8

Body

{}

Retrieve Cloud Account Session via intermediary
POST`/secrets/cloud-accounts/{cloudAccountId}/{secretId}/session-keys/via/cloud-accounts/{viaCloudAccountId}/{viaSecretId}`

First retrieve viaSecretId session, then retreve and return secretId session using that. This works for AWS only. X-Via-Secrets-Token is used to fetch Via Secret from Vault.

The use case is to have a set of static credentials to assume (cross-account) role. This allows (1) Secrets Service on-prem - without instance profile - to work with multiple AWS accounts; (2) Secrets Service in public cloud to issue GovCloud session and vice versa.

URI Parameters

HideShow

cloudAccountId: string (required) Example: 123
ID of the Cloud Account
secretId: string (required) Example: 02a669c0-543b-432f-a11d-fb21f29c7200
ID of the Secret
viaCloudAccountId: string (required) Example: 456
ID of the Via Cloud Account
viaSecretId: string (required) Example: 4676a1a6-dd9c-4f86-b4fc-9c049c0674e7
ID of the Via Secret

POST http://secrets.agilestacks.com/api/v1/secrets/environments/123

Requestsexample 1

Headers

Content-Type: application/json; charset=utf-8
X-Secrets-Token: user-token

Body

{
  "name": "component.postgresql.password",
  "kind": "usernamePassword",
  "username": "automation-hub",
  "password": "jai0eite3X"
}

Responses201403400502504

Headers

Content-Type: application/json; charset=utf-8
Location: /api/v1/environments/123/secrets/02a669c0-543b-432f-a11d-fb21f29c7200

Body

{
  "id": "02a669c0-543b-432f-a11d-fb21f29c7200"
}

This response has no content.

Headers

Content-Type: application/json; charset=utf-8

Body

"errors": [
            {
                "type": "badRequest",
                "detail": "Error parse JSON input",
                "meta": {
                    "errors": {
                        "type": "badRequest",
                        "detail": "Error parse JSON input",
                        "meta": {
                            "stack":"Error: Error parse JSON input...js:76:19)"
                        }
                    }
                }
            }
        ]
    }

This response has no content.

Create Secret
POST`/secrets/{entityKind}/{entityId}`

URI Parameters

HideShow

entityKind: string (required) Example: environments
Entity type identifier
entityId: string (required) Example: 123
ID of the Entity

POST http://secrets.agilestacks.com/api/v1/secrets/instances/123/copy/instances/102/4b71b933-f1e0-4a63-a113-6fb813cfb4a7

Requestsexample 1

Headers

Content-Type: application/json; charset=utf-8
X-Secrets-Token: user-token

Body

{
  "kind": "privateKey"
}

Responses201403409400502504

Headers

Content-Type: application/json; charset=utf-8
Location: /api/v1/instances/123/secrets/02a669c0-543b-432f-a11d-fb21f29c7200

Body

{
  "id": "02a669c0-543b-432f-a11d-fb21f29c7200"
}

This response has no content.

Headers

Content-Type: application/json; charset=utf-8

Body

"errors": [
            {
                "type": "badRequest",
                "detail": "Error parse JSON input",
                "meta": {
                    "errors": {
                        "type": "badRequest",
                        "detail": "Error parse JSON input",
                        "meta": {
                            "stack":"Error: Error parse JSON input...js:76:19)"
                        }
                    }
                }
            }
        ]
    }

This response has no content.

Create Secret by example
POST`/secrets/{entityKind}/{entityId}/copy/{fromEntityKind}/{fromEntityId}/{fromId}`

Create a new secret by copying existing secret, optionally changing or adding secret’s fields.

If supplied, kind must match source secret kind. If kind = 'cloudAccount' is presented in the body, then cloud must be specified and must match source secret cloud.

URI Parameters

HideShow

entityKind: string (required) Example: instances
Entity type identifier
entityId: string (required) Example: 123
ID of the Entity
fromEntityKind: string (required) Example: instances
Source Entity type identifier
fromEntityId: string (required) Example: 102
Source ID of the Entity
fromId: string (required) Example: 4b71b933-f1e0-4a63-a113-6fb813cfb4a7
Source Secret ID

PUT http://secrets.agilestacks.com/api/v1/secrets/environments/123/02a669c0-543b-432f-a11d-fb21f29c7200

Requestsexample 1

Headers

Content-Type: application/json; charset=utf-8
X-Secrets-Token: user-token

Body

{
  "name": "component.postgresql.password",
  "kind": "password",
  "username": "automation-hub",
  "password": "jai0eite3X"
}

Responses204404403400409502504

This response has no content.

Headers

Content-Type: application/json; charset=utf-8

Body

"errors": [
            {
                "type": "badRequest",
                "detail": "`password` field is not set",
                "meta": {
                    "errors": {
                        "type": "badRequest",
                        "detail": "`password` field is not set",
                        "meta": {
                            "stack":"Error: `password` field is not set...js:76:19)"
                        }
                    }
                }
            }
        ]
    }

Headers

Content-Type: application/json; charset=utf-8

Body

"errors": [
        {
            "type": "badRequest",
            "detail": "`kind` doesn't match",
            "meta": {
                "errors": {
                    "type": "badRequest",
                    "detail": "`kind` doesn't match",
                    "meta": {
                        "stack":"Error: `kind` doesn't match...js:76:19)"
                    }
                }
            }
        }
    ]
}

This response has no content.

Update Secret
PUT`/secrets/{entityKind}/{entityId}/{secretId}`

The secret kind must match otherwise 409 Conflict will be returned.

URI Parameters

HideShow

entityKind: string (required) Example: environments
Entity type identifier
entityId: string (required) Example: 123
ID of the Entity
secretId: string (required) Example: 02a669c0-543b-432f-a11d-fb21f29c7200
ID of the Secret

DELETE http://secrets.agilestacks.com/api/v1/secrets/environments/123/02a669c0-543b-432f-a11d-fb21f29c7200

Requestsexample 1

Headers

X-Secrets-Token: user-token

Responses204404403502504

This response has no content.

Delete Secret
DELETE`/secrets/{entityKind}/{entityId}/{secretId}`

URI Parameters

HideShow

entityKind: string (required) Example: environments
Entity type identifier
entityId: string (required) Example: 123
ID of the Entity
secretId: string (required) Example: 02a669c0-543b-432f-a11d-fb21f29c7200
ID of the Secret

DELETE http://secrets.agilestacks.com/api/v1/secrets/instances/123

Requestsexample 1

Headers

X-Secrets-Token: user-token

Responses204404403502504

This response has no content.

Delete all Entity Secrets
DELETE`/secrets/{entityKind}/{entityId}`

Recursively delete all secrets under specific path.

URI Parameters

HideShow

entityKind: string (required) Example: instances
Entity type identifier
entityId: string (required) Example: 123
ID of the Entity

User ¶

User is currently an Okta user and is addressed by Okta user Id with prefix okta-, e.g. okta-00ub0oNGTSWTBKOLGLNR.

PUT http://secrets.agilestacks.com/api/v1/users/okta-00ub0oNGTSWTBKOLGLNR

Requestsexample 1

Headers

X-Secrets-Token: high-privilege-auth-service-token

Responses201403502504

Headers

Content-Type: application/json; charset=utf-8

Body

{
  "roleId": "f2db06c7-1b3c-9262-1116-fa1842a5c567"
}

This response has no content.

Create User
PUT`/users/{userId}`

Returned roleId must be saved by calling service for use with /login. This method is idempotent and it will reset the policies associated with the role in case role already exist. (Policies controls access to Environment, Cloud Account, etc. secrets)

URI Parameters

HideShow

userId: string (required) Example: okta-00ub0oNGTSWTBKOLGLNR
ID of the User

DELETE http://secrets.agilestacks.com/api/v1/users/okta-00ub0oNGTSWTBKOLGLNR

Requestsexample 1

Headers

X-Secrets-Token: high-privilege-auth-service-token

Responses204404403502504

This response has no content.

Delete User
DELETE`/users/{userId}`

URI Parameters

HideShow

userId: string (required) Example: okta-00ub0oNGTSWTBKOLGLNR
ID of the User

PUT http://secrets.agilestacks.com/api/v1/users/okta-00ub0oNGTSWTBKOLGLNR/environments

Requestsexample 1

Headers

Content-Type: application/json; charset=utf-8
X-Secrets-Token: high-privilege-automation-hub-token | high-privilege-auth-service-token?

Body

{
  "environments": [
    "env id 1",
    "env id 2"
  ],
  "cloudAccounts": [
    "cloud account id 1",
    "cloud account id 2"
  ],
  "etc.": []
}

Responses204404403400502504

This response has no content.

Headers

Content-Type: application/json; charset=utf-8

Body

"errors": [
            {
                "type": "badRequest",
                "detail": "`environments` field is not set",
                "meta": {
                    "errors": {
                        "type": "badRequest",
                        "detail": "`environments` field is not set",
                        "meta": {
                            "stack":"Error: `environments` field is not set...js:76:19)"
                        }
                    }
                }
            }
        ]
    }

This response has no content.

Update User access to secrets
PUT`/users/{userId}/{entityKind}`

Put a list of entityKind Id-s the user has access to. Only one corresponding key must be specified in request body.

URI Parameters

HideShow

userId: string (required) Example: okta-00ub0oNGTSWTBKOLGLNR
ID of the User
entityKind: string (required) Example: environments
Entity type identifier

POST http://secrets.agilestacks.com/api/v1/users/okta-00ub0oNGTSWTBKOLGLNR/login

Requestsexample 1

Headers

Content-Type: application/json; charset=utf-8
X-Secrets-Token: low-privilege-auth-service-token

Body

{
  "roleId": "0dcc3856-c11b-9673-bd30-b083cbae4987"
}

Responses200404403400502504

Headers

Content-Type: application/json; charset=utf-8

Body

{
  "token": "c9086cfc-c1a4-4609-546d-1f9d860c8ac3",
  "ttl": 3600
}

This response has no content.

Headers

Content-Type: application/json; charset=utf-8

Body

{
  "errors": [
    {
      "type": "badRequest",
      "detail": "Either `highPrivRoleId` or `lowPrivRoleId` field is not set",
      "meta": {
        "errors": {
          "type": "badRequest",
          "detail": "Either `highPrivRoleId` or `lowPrivRoleId` field is not set",
          "meta": {
            "stack": "Error: Either `highPrivRoleId` or `lowPrivRoleId`...js:76:19)"
          }
        }
      }
    }
  ]
}

This response has no content.

Login User to obtain Secrets Token
POST`/users/{userId}/login`

URI Parameters

HideShow

userId: string (required) Example: okta-00ub0oNGTSWTBKOLGLNR
ID of the User

Apps ¶

Currently recognised apps are:

Authentication Service with Id authentication-service;
Automation Hub with Id automation-hub.

Request source IP CIDR will be checked too.

POST http://secrets.agilestacks.com/api/v1/apps/authentication-service/login

Requestsexample 1

Headers

Content-Type: application/json; charset=utf-8

Body

{
  "highPrivRoleId": "f696ed85-eab6-484f-8f1b-adac94cffc08",
  "lowPrivRoleId": "41bc5ff3-077c-4613-9419-77fe89267113"
}

Responses200404403400502504

Headers

Content-Type: application/json; charset=utf-8

Body

{
  "highPrivToken": "89b144e3-d785-46b4-ac3f-5cc504bfc624",
  "lowPrivToken": "4f5b5510-a6ac-41e1-b4bc-bcff4f522769",
  "ttl": 3600
}

This response has no content.

Headers

Content-Type: application/json; charset=utf-8

Body

{
  "errors": [
    {
      "type": "badRequest",
      "detail": "`highPrivRoleId` field is not set",
      "meta": {
        "errors": {
          "type": "badRequest",
          "detail": "`highPrivRoleId` field is not set",
          "meta": {
            "stack": "Error: `highPrivRoleId` field is not set...js:76:19)"
          }
        }
      }
    }
  ]
}

This response has no content.

Login App to obtain Secrets Token
POST`/apps/{appId}/login`

URI Parameters

HideShow

appId: string (required) Example: authentication-service
ID of the Service / App

Token ¶

POST http://secrets.agilestacks.com/api/v1/tokens/renew

Requestsexample 1

Headers

X-Secrets-Token: token

Responses200403502504

Body

{
  "ttl": 3600
}

This response has no content.

Renew Token
POST`/tokens/renew`

X-Secrets-Token is the token to operate on.

POST http://secrets.agilestacks.com/api/v1/tokens/revoke

Requestsexample 1

Headers

X-Secrets-Token: token

Responses204403502504

This response has no content.

Revoke Token
POST`/tokens/revoke`

Authentication Service should revoke user token on user logout.

X-Secrets-Token is the token to operate on.

Generated by aglio on 02 May 2020

API Endpoint

Resource Group ¶

Secret ¶

Headers

Headers

Body

Retrieve SecretGET/secrets/{entityKind}/{entityId}/{secretId}

Headers

Body

Headers

Body

Headers

Body

Headers

Body

Retrieve Cloud Account SessionPOST/secrets/cloud-accounts/{cloudAccountId}/{secretId}/session-keys

Headers

Body

Headers

Body

Retrieve Cloud Account Session via intermediaryPOST/secrets/cloud-accounts/{cloudAccountId}/{secretId}/session-keys/via/cloud-accounts/{viaCloudAccountId}/{viaSecretId}

Headers

Body

Headers

Body

Headers

Body

Create SecretPOST/secrets/{entityKind}/{entityId}

Headers

Body

Headers

Body

Headers

Body

Create Secret by examplePOST/secrets/{entityKind}/{entityId}/copy/{fromEntityKind}/{fromEntityId}/{fromId}

Headers

Body

Headers

Body

Headers

Body

Update SecretPUT/secrets/{entityKind}/{entityId}/{secretId}

Headers

Delete SecretDELETE/secrets/{entityKind}/{entityId}/{secretId}

Headers

Delete all Entity SecretsDELETE/secrets/{entityKind}/{entityId}

User ¶

Headers

Headers

Body

Create UserPUT/users/{userId}

Headers

Delete UserDELETE/users/{userId}

Headers

Body

Headers

Body

Update User access to secretsPUT/users/{userId}/{entityKind}

Headers

Body

Headers

Body

Headers

Body

Login User to obtain Secrets TokenPOST/users/{userId}/login

Apps ¶

Headers

Body

Headers

Body

Headers

Body

Login App to obtain Secrets TokenPOST/apps/{appId}/login

Token ¶

Headers

Body

Renew TokenPOST/tokens/renew

Headers

Revoke TokenPOST/tokens/revoke

Retrieve Secret
GET`/secrets/{entityKind}/{entityId}/{secretId}`

Retrieve Cloud Account Session
POST`/secrets/cloud-accounts/{cloudAccountId}/{secretId}/session-keys`

Retrieve Cloud Account Session via intermediary
POST`/secrets/cloud-accounts/{cloudAccountId}/{secretId}/session-keys/via/cloud-accounts/{viaCloudAccountId}/{viaSecretId}`

Create Secret
POST`/secrets/{entityKind}/{entityId}`

Create Secret by example
POST`/secrets/{entityKind}/{entityId}/copy/{fromEntityKind}/{fromEntityId}/{fromId}`

Update Secret
PUT`/secrets/{entityKind}/{entityId}/{secretId}`

Delete Secret
DELETE`/secrets/{entityKind}/{entityId}/{secretId}`

Delete all Entity Secrets
DELETE`/secrets/{entityKind}/{entityId}`

Create User
PUT`/users/{userId}`

Delete User
DELETE`/users/{userId}`

Update User access to secrets
PUT`/users/{userId}/{entityKind}`

Login User to obtain Secrets Token
POST`/users/{userId}/login`

Login App to obtain Secrets Token
POST`/apps/{appId}/login`

Renew Token
POST`/tokens/renew`

Revoke Token
POST`/tokens/revoke`