API.apib

FORMAT: 1A
HOST: http://secrets.agilestacks.com/api/v1

# Secrets Service API

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](https://github.com/agilestacks/secrets-service/blob/master/README.md) 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.

## Secret [/secrets/{entityKind}/{entityId}/{secretId}]

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


### Retrieve Secret [GET]

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:

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

Cloud account entity:

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

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

+ Request

    + Headers

            X-Secrets-Token: user-token

+ Response 200 (application/json; charset=utf-8)

    + Body

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

+ Response 404

+ Response 403

+ Response 502

+ Response 504


### 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](http://docs.aws.amazon.com/STS/latest/APIReference/API_GetSessionToken.html):

> 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"]`.

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

+ Request

    + Headers

            X-Secrets-Token: user-token

    + Body

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


+ Response 200 (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": "..."
                }
            }

+ Response 404

+ Response 403

+ Response 405 (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)"
                                }
                            }
                        }
                    }
                ]
            }

+ Response 504

+ Response 502 (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 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.

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

+ Request

    + Headers

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

    + Body

            {
            }


+ Response 200 (application/json; charset=utf-8)

    + Body

            {
            }

### Create Secret [POST /secrets/{entityKind}/{entityId}]

+ Parameters
    + entityKind: `environments` - Entity type identifier
    + entityId: `123` (string) - ID of the Entity

+ Request (application/json; charset=utf-8)

    + Headers

            X-Secrets-Token: user-token

    + Body

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

+ Response 201 (application/json; charset=utf-8)

    + Headers

            Location: /api/v1/environments/123/secrets/02a669c0-543b-432f-a11d-fb21f29c7200

    + Body

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

+ Response 403

+ Response 400 (application/json; charset=utf-8)

            "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)"
                                }
                            }
                        }
                    }
                ]
            }

+ Response 502

+ Response 504


### 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`.

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

+ Request (application/json; charset=utf-8)

    + Headers

            X-Secrets-Token: user-token

    + Body

            {
                "kind": "privateKey"
            }

+ Response 201 (application/json; charset=utf-8)

    + Headers

            Location: /api/v1/instances/123/secrets/02a669c0-543b-432f-a11d-fb21f29c7200

    + Body

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

+ Response 403

+ Response 409

+ Response 400 (application/json; charset=utf-8)

            "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)"
                                }
                            }
                        }
                    }
                ]
            }

+ Response 502

+ Response 504


### Update Secret [PUT]

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

+ Request (application/json; charset=utf-8)

    + Headers

            X-Secrets-Token: user-token

    + Body

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

+ Response 204

+ Response 404

+ Response 403

+ Response 400 (application/json; charset=utf-8)

            "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)"
                                }
                            }
                        }
                    }
                ]
            }

+ Response 409 (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)"
                                }
                            }
                        }
                    }
                ]
            }

+ Response 502

+ Response 504


### Delete Secret [DELETE]

+ Request

    + Headers

            X-Secrets-Token: user-token

+ Response 204

+ Response 404

+ Response 403

+ Response 502

+ Response 504


### Delete all Entity Secrets [DELETE /secrets/{entityKind}/{entityId}]

Recursively delete all secrets under specific path.

+ Parameters
    + entityKind: `instances` - Entity type identifier
    + entityId: `123` (string) - ID of the Entity

+ Request

    + Headers

            X-Secrets-Token: user-token

+ Response 204

+ Response 404

+ Response 403

+ Response 502

+ Response 504


## User [/users/{userId}]

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

+ Parameters
    + userId: `okta-00ub0oNGTSWTBKOLGLNR` (string) - ID of the User


### Create User [PUT]

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)

+ Request

    + Headers

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

+ Response 201 (application/json; charset=utf-8)

    + Body

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

+ Response 403

+ Response 502

+ Response 504


### Delete User [DELETE]

+ Request

    + Headers

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

+ Response 204

+ Response 404

+ Response 403

+ Response 502

+ Response 504


### 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.

+ Parameters
    + userId: `okta-00ub0oNGTSWTBKOLGLNR` (string) - ID of the User
    + entityKind: `environments` (string) - Entity type identifier

+ Request (application/json; charset=utf-8)

    + Headers

            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.": []
            }

+ Response 204

+ Response 404

+ Response 403

+ Response 400 (application/json; charset=utf-8)

            "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)"
                                }
                            }
                        }
                    }
                ]
            }

+ Response 502

+ Response 504


### Login User to obtain Secrets Token [POST /users/{userId}/login]

Login to obtain `user-token`.

+ Parameters
    + userId: `okta-00ub0oNGTSWTBKOLGLNR` (string) - ID of the User

+ Request (application/json; charset=utf-8)

    + Headers

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

    + Body

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

+ Response 200 (application/json; charset=utf-8)

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

+ Response 404

+ Response 403

+ Response 400 (application/json; charset=utf-8)

            {
                "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)"
                                }
                            }
                        }
                    }
                ]
            }

+ Response 502

+ Response 504



## Apps [/apps/{appId}]

Currently recognised apps are:

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

Request source IP CIDR will be checked too.

+ Parameters
    + appId: `authentication-service` (string) - ID of the Service / App


### Login App to obtain Secrets Token [POST /apps/{appId}/login]

Login to obtain `high` and `low-privilege-auth-service-token`-s .

+ Parameters
    + appId: `authentication-service` (string) - ID of the Service / App

+ Request (application/json; charset=utf-8)

    + Body

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

+ Response 200 (application/json; charset=utf-8)

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

+ Response 404

+ Response 403

+ Response 400 (application/json; charset=utf-8)

            {
                "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)"
                                }
                            }
                        }
                    }
                ]
            }

+ Response 502

+ Response 504



## Token [/tokens]


### Renew Token [POST /tokens/renew]

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

+ Request

    + Headers

            X-Secrets-Token: token

+ Response 200

    + Body

            {
                "ttl": 3600
            }

+ Response 403

+ Response 502

+ Response 504


### Revoke Token [POST /tokens/revoke]

Authentication Service should revoke user token on user logout.

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

+ Request

    + Headers

            X-Secrets-Token: token

+ Response 204

+ Response 403

+ Response 502

+ Response 504