API

Confidant has an API that can be used for programmatic access from the UI, libraries, or CLIs. Authentication is required for all endpoints, and the allowed types of authentication (kmsauth, SAML, OAuth, etc.) are based on your configuration and RBAC settings. See configuration and RBAC documentation for more information about authentication and authorization.

API route documentation

Resource	Operation	Description
	GET /v1/saml/metadata
	POST /v1/saml/consume
	GET /v1/saml/logout
	GET /v1/saml/login
	GET /v1/saml/debug
	POST /v1/credentials/(id)/archive
	GET /v1/jwks/public/(environment)
	GET /v1/jwks/token
	GET /v1/jwks/token/(id)
Authenticate	POST /v1/login	Send user through login flow.
	GET /v1/login
Certificate	GET /v1/certificates/(ca)/(cn)	Get certificate from the provided CA, for the
	POST /v1/certificates/(ca)	Issue and get a certificate from the provided
Certificate Authorities	GET /v1/cas	Get a list of the detailed
	GET /v1/cas/(ca)	Get the detailed certificate
Client Configuration	GET /v1/client_config	Get configuration to help clients
Credential	POST /v1/credentials	Create a credential using the data provided in
	PUT /v1/credentials/(id)/(to_revision)	Revert the provided credential to the provided
	GET /v1/credentials/(id)	Get a credential from the provided id.
	PUT /v1/credentials/(id)	Update the provided credential using the data
Credential Diff	GET /v1/credentials/(id)/(old_revision)/(new_revision)	Get a diff of two revisions of a credential.
Credential History	GET /v1/archive/credentials	Get a list of the metadata for all history
Credential Mappings	GET /v1/credentials/(id)/services	Get a list of services that this
Credential Revisions	GET /v1/archive/credentials/(id)	Get a list of the metadata of all the
Credentials	GET /v1/credentials	Get a list of the metadata for all current
Email Address	POST /v1/user/email	Get the email address associated with the
	GET /v1/user/email
IAM Roles	GET /v1/roles	Get a list of IAM roles from the configured
KMS Grants	PUT /v1/grants/(id)	Ensure grants are set for the provided service ID.
	GET /v1/grants/(id)	Get grants for the provided service ID.
Random Value	GET /v1/value_generator	Get a randomly generated value, for use in
Service	PUT /v1/services/(id)/(to_revision)	Revert the provided service to the provided
	GET /v1/services/(id)	Get a service object from the provided service ID.
	PUT /v1/services/(id)	Create or update a service to credential mapping
Service Diff	GET /v1/services/(id)/(old_revision)/(new_revision)	Get a diff of two revisions of a service.
Service History	GET /v1/archive/services	Get a list of service history revisions.
	GET /v1/archive/services/(id)	Get a list of revisions for the specified
Services	GET /v1/services	Get a list of current service revisions.

GET /v1/archive/credentials

Returns a list of the metadata of all the history revisions of credentials.

Example request:

GET /v1/archive/credentials/abcd12345bf4f1cafe8e722d3860404

Query Parameters

• next_page (string) – If paged results were returned in a call, this query string can be used to fetch the next page.

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "revisions": [
    {
      "id": "abcd12345bf4f1cafe8e722d3860404-1",
      "name": "Example Credential",
      "credential_keys": [],
      "credential_pairs": {},
      "metadata": {
        "example_metadata_key": "example_value"
      },
      "revision": 1,
      "enabled": true,
      "documentation": "Example documentation",
      "modified_date": "2019-12-16T23:16:11.413299+00:00",
      "modified_by": "rlane@example.com",
      "permissions": {}
    },
    ...
  ],
  next_page: null
}

Response Headers

• Content-Type – application/json

Status Codes

• 200 OK – Success

• 403 Forbidden – Client does not have permissions to list credentials

GET /v1/archive/services

Get a list of service history revisions.

Example request:

GET /v1/archive/services

Query Parameters

• next_page (string) – If paged results were returned in a call, this query string can be used to fetch the next page.

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "services": [
    {
      "id": "example-development-1",
      "revision": 1,
      "enabled": true,
      "modified_date": "2019-12-16T23:16:11.413299+00:00",
      "modified_by": "rlane@example.com",
      "account": null,
      "credentials": [],
      "blind_credentials": [],
      "permissions": {}
    },
    ...
  ],
  "next_page": null
}

Response Headers

• Content-Type – application/json

Status Codes

• 200 OK – Success

• 403 Forbidden – Client does not have permissions to list services.

GET /v1/saml/metadata

Generate SAML metadata XML describing the service endpoints.

POST /v1/saml/consume

The SAML attribute consumer service receives POST callbacks from the IdP.

GET /v1/saml/logout

This dual purpose route both initiates SingleLogOut redirects to the IdP and receives the HTTP-REDIRECT callback (also a GET) from the IdP post logout.

POST /v1/user/email

Get the email associated with the currently authenticated user.

Example request:

GET /v1/user/email

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "email": "rlane@example.com"
}

Response Headers

• Content-Type – application/json

Status Codes

• 200 OK – Success

GET /v1/user/email

Get the email associated with the currently authenticated user.

Example request:

GET /v1/user/email

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "email": "rlane@example.com"
}

Response Headers

• Content-Type – application/json

Status Codes

• 200 OK – Success

GET /v1/saml/login

Redirect to the SAML login page. You don’t normally need to hit this since any page with @authnz.require_auth will redirect to login.

GET /v1/saml/debug

Debug endpoint to show SAML attributes.

GET /v1/value_generator

Returns a randomly generated value, for use in credential pairs.

Example request:

GET /v1/value_generator

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "value": "c5S0w08YwU4PY3EZ7eQf4QYYUIT6ryyKOydhjyTti9pjPuMU00"
}

Response Headers

• Content-Type – application/json

Status Codes

• 200 OK – Success

GET /v1/client_config

Get configuration to help clients bootstrap themselves.

Example request:

GET /v1/client_config

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "defined": {},
  "generated": {
    "kms_auth_manage_grants": false,
    "aws_accounts": [],
    "xsrf_cookie_name": "XSRF_COOKIE",
    "maintenance_mode": false,
    "history_page_limit": 500,
    "permissions": {
      "list": true,
      "create": true
    }
  }
}

Response Headers

• Content-Type – application/json

Status Codes

• 200 OK – Success

GET /v1/credentials

Returns a list of the metadata of all the current revision of credentials.

Example request:

GET /v1/credentials

Query Parameters

• next_page (string) – If paged results were returned in a call, this query string can be used to fetch the next page.

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "credentials": [
    {
      "id": "abcd12345bf4f1cafe8e722d3860404",
      "name": "Example Credential",
      "credential_keys": [],
      "credential_pairs": {},
      "metadata": {
        "example_metadata_key": "example_value"
      },
      "revision": 1,
      "enabled": true,
      "documentation": "Example documentation",
      "modified_date": "2019-12-16T23:16:11.413299+00:00",
      "modified_by": "rlane@example.com",
      "permissions": {}
    },
    ...
  ],
  next_page: null
}

Response Headers

• Content-Type – application/json

Status Codes

• 200 OK – Success

• 403 Forbidden – Client does not have permissions to list credentials.

POST /v1/credentials

Create a credential using the data provided in the POST body.

Example request:

POST /v1/credentials

Request JSON Object

• name (string) – The friendly name for the credential. (required)

• Dictionary{string – string} credential_pairs: A dictionary of arbitrary key/value pairs to be encrypted at rest. (required)

• Dictionary{string – string} metadata: A dictionary of arbitrary key/ value pairs for custom per-credential end-user extensions. This is not encrypted at rest.

• enabled (boolean) – Whether or not this credential is enabled. (default: true)

• documentation (string) – End-user provided documentation for this credential. (required)

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

 {
   "id": "abcd12345bf4f1cafe8e722d3860404",
   "name": "Example Credential",
   "credential_keys": ["example_credential_key"],
   "credential_pairs": {
     "example_credential_key": "example_credential_value"
   },
   "metadata": {
     "example_metadata_key": "example_value"
   },
   "revision": 1,
   "enabled": true,
   "documentation": "Example documentation",
   "modified_date": "2019-12-16T23:16:11.413299+00:00",
   "modified_by": "rlane@example.com",
   "permissions": {
     "metadata": true,
     "get": true,
     "update": true
   }
 }

Response Headers

• Content-Type – application/json

Status Codes

• 200 OK – Success

• 400 Bad Request – Invalid input; either the data provided was not in the correct format, or a required field was not provided.

• 403 Forbidden – Client does not have access to create credentials.

GET /v1/services

Get a list of current service revisions.

Example request:

GET /v1/services

Query Parameters

• next_page (string) – If paged results were returned in a call, this query string can be used to fetch the next page.

• limit (int) – Limit of items per each page (required for pagination)

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "services": [
    {
      "id": "example-development",
      "revision": 1,
      "enabled": true,
      "modified_date": "2019-12-16T23:16:11.413299+00:00",
      "modified_by": "rlane@example.com",
      "account": null,
      "credentials": [],
      "blind_credentials": [],
      "permissions": {}
    },
    ...
  ],
  "next_page": null
}

Response Headers

• Content-Type – application/json

Status Codes

• 200 OK – Success

• 403 Forbidden – Client does not have permissions to list services.

POST /v1/login

Send user through login flow. Response depends on configured authentication plugin.

Example request:

GET /v1/login

GET /v1/login

Send user through login flow. Response depends on configured authentication plugin.

Example request:

GET /v1/login

GET /v1/roles

Get a list of IAM roles from the configured AWS account.

Example request:

GET /v1/roles

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "roles": [
    'example-development',
    'example2-development',
    ...
  ]
}

Response Headers

• Content-Type – application/json

Status Codes

• 200 OK – Success

• 403 Forbidden – Client does not have permissions to list services.

GET /v1/cas

List the configured CAs.

Example request:

GET /v1/cas

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "cas": [
    "example-ca": {
      "certificate": "---...BEGIN...",
      "certificate_chain": "---...BEGIN...",
      "tags": {
        "hello": "world"
     },
     ...
  ]
}

Response Headers

• Content-Type – application/json

Status Codes

• 200 OK – success

• 403 Forbidden – client does not have access to list CAs

GET /v1/credentials/(id)/services

Returns a list of services that this credential is mapped to.

Example request:

GET /v1/credentials/abcd12345bf4f1cafe8e722d3860404/services

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "services": ["example-development", "example2-development"]
}

Response Headers

• Content-Type – application/json

Status Codes

• 200 OK – Success

• 403 Forbidden – Client does not have permissions to get metadata for the provided credential.

POST /v1/credentials/(id)/archive

Archive the provided credential. Example request:

POST /v1/credentials/abcd12345bf4f1cafe8e722d3860404/archive

Parameters

• id – The credential ID to update.

Request JSON Object

• force (bool) – Run the archive operation, if false will only validate the provided input

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

 {
   "result": "success"
 }

Response Headers

• Content-Type – application/json

Status Codes

• 200 OK – Success

• 400 Bad Request – Invalid input or state

• 403 Forbidden – Client does not have access to archive the provided credential ID.

GET /v1/archive/credentials/(id)

Returns a list of the metadata of all the revisions of the provided credential.

Example request:

GET /v1/archive/credentials/abcd12345bf4f1cafe8e722d3860404

Query Parameters

• next_page (string) – If paged results were returned in a call, this query string can be used to fetch the next page.

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "revisions": [
    {
      "id": "abcd12345bf4f1cafe8e722d3860404-1",
      "name": "Example Credential",
      "credential_keys": [],
      "credential_pairs": {},
      "metadata": {
        "example_metadata_key": "example_value"
      },
      "revision": 1,
      "enabled": true,
      "documentation": "Example documentation",
      "modified_date": "2019-12-16T23:16:11.413299+00:00",
      "modified_by": "rlane@example.com",
      "permissions": {}
    },
    ...
  ],
  next_page: null
}

Response Headers

• Content-Type – application/json

Status Codes

• 200 OK – Success

• 403 Forbidden – Client does not have permissions to get credential metadata for the provided credential ID.

• 404 Not Found – The provided credential ID does not exist.

GET /v1/archive/services/(id)

Get a list of revisions for the specified service ID.

Example request:

GET /v1/archive/services/example-development

Parameters

• id (str) – The service ID to get.

Query Parameters

• next_page (string) – If paged results were returned in a call, this query string can be used to fetch the next page.

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "revisions": [
    {
      "id": "example-development-1",
      "revision": 1,
      "enabled": true,
      "modified_date": "2019-12-16T23:16:11.413299+00:00",
      "modified_by": "rlane@example.com",
      "account": null,
      "credentials": [],
      "blind_credentials": [],
      "permissions": {}
    },
    ...
  ],
  "next_page": null
}

Response Headers

• Content-Type – application/json

Status Codes

• 200 OK – Success

• 403 Forbidden – Client does not have permissions to get metadata for the provided service ID.

• 404 Not Found – Specified ID does not exist.

GET /v1/jwks/public/(environment)

Returns a the public JWKS for the requested environment

Example request:

GET /v1/jwks/public/staging

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "kty": "RSA",
  "kid": "staging",
  "n": "123...",
  "e": "AQAB",
  "alg" "RS256",
}

Response Headers

• Content-Type – application/json

Status Codes

• 200 OK – Success

• 404 Not Found – Public key not found for this environment

GET /v1/jwks/token

GET /v1/jwks/token/(id)

Returns a JWT for the authenticated service

Example request:

GET /v1/jwks/token/some-id

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "token": "ey..."
}

Response Headers

• Content-Type – application/json

Status Codes

• 200 OK – Success

• 400 Bad Request – JWTs are not supported for this user

GET /v1/certificates/(ca)/(cn)

Get a certificate from the provided CA, for the provided CN.

Example request:

GET /v1/certificates/example-ca/service.example.com

Parameters

• ca (str) – The friendly name of the certificate authority to issue a certificate against.

• cn (str) – The canonical name attribute to use in the issued certificate.

Query Parameters

• san (string) – A subject alternative name attribute to use in the issued certificate. This query parameter can be provided multiple times

• validity (int) – The length (in days) that the issued certificate should be valid for. If this value is longer than the server defined maximum validity length, the validity will be set to the maximum validity length.

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "certificate": "---...BEGIN...",
  "certificate_chain": "---...BEGIN...",
  "key": "---...BEGIN..."
}

Response Headers

• Content-Type – application/json

Status Codes

• 200 OK – success

• 403 Forbidden – client does not have access to generate the requested certificate.

POST /v1/certificates/(ca)

Get a certificate from the ca provided in the url, using the CSR, validity and san provided in the POST body.

Example request:

POST /v1/certificates/example-ca

Request JSON Object

• ca (string) – The friendly name of the certificate authority to issue a certificate against.

• san (List[string]) – a list of subject alternative name attributes to use in the issued certificate. This query parameter can be provided multiple times

• validity (int) – The length (in days) that the issued certificate. should be valid for. If this value is longer than the server defined maximum validity length, the validity will be set to the maximum validity length.

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "certificate": "---...BEGIN...",
  "certificate_chain": "---...BEGIN..."
}

Response Headers

• Content-Type – application/json

Status Codes

• 200 OK – Success

• 400 Bad Request – Invalid input; either the CSR was unsbale to be decoded, or was missing from the request.

• 403 Forbidden – Client does not have access to generate the requested certificate.

GET /v1/credentials/(id)/(old_revision)/(new_revision)

Returns a diff between old_revision and new_revision for the provided credential id.

Example request:

GET /v1/credentials/abcd12345bf4f1cafe8e722d3860404/1/2

Parameters

• id (str) – The credential ID to get.

• old_revision (int) – One of the two revisions to diff against.

• new_revision (int) – One of the two revisions to diff against.

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "name": {
    "added": "New credential name",
    "removed": "Example credential name"
  },
  "credential_pairs": {
    "added": [
      "api_key",
      "api_user"
    ],
    "removed": [
      "api_certificate"
    ]
  },
  "metadata": {
    "added": "example_key"
  },
  "enabled": {
    "added": false,
    "removed": true
  },
  "documentation": {
    "added": "The way you rotate this credential is to...",
    "removed": "Example documentation"
  },
  "modified_date": {
    "added": "2019-12-16T23:16:11.413299+00:00",
    "removed": "2019-11-16T23:16:11.413299+00:00"
  },
  "modified_by": {
    "added": "rlane@example.com",
    "removed": "testuser@example.com"
  }
}

Response Headers

• Content-Type – application/json

Status Codes

• 200 OK – Success

• 403 Forbidden – Client does not have permissions to diff the provided credential ID.

• 404 Not Found – The provided credential ID or one of the provided revisions does not exist.

PUT /v1/credentials/(id)/(to_revision)

Revert the provided credential to the provided revision.

Example request:

PUT /v1/credentials/abcd12345bf4f1cafe8e722d3860404/1

Parameters

• id (str) – The credential ID to revert.

• to_revision (int) – The revision to revert this credential to.

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

 {
   "id": "abcd12345bf4f1cafe8e722d3860404",
   "name": "Example Credential",
   "credential_keys": ["example_credential_key"],
   "credential_pairs": {},
   "metadata": {
     "example_metadata_key": "example_value"
   },
   "revision": 1,
   "enabled": true,
   "documentation": "Example documentation",
   "modified_date": "2019-12-16T23:16:11.413299+00:00",
   "modified_by": "rlane@example.com",
   "permissions": {
     "metadata": true,
     "get": true,
     "update": true
   }
 }

Response Headers

• Content-Type – application/json

Status Codes

• 200 OK – Success

• 400 Bad Request – Invalid input; the update would create conflicting credential keys in a mapped service.

• 403 Forbidden – Client does not have access to revert the provided credential ID.

GET /v1/credentials/(id)

Returns a credential object for the provided credential id.

Example request:

GET /v1/credentials/abcd12345bf4f1cafe8e722d3860404

Parameters

• id (str) – The credential ID to get.

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "...",
  "name": "Example Credential",
  "credential_keys": [
    "api_key",
    "api_user"
  ],
  "credential_pairs": {
    "api_key": "1234",
    "api_user": "example_user"
  },
  "metadata": {
    "example_metadata_key": "example_value"
  },
  "revision": 1,
  "enabled": true,
  "documentation": "Example documentation",
  "modified_date": "2019-12-16T23:16:11.413299+00:00",
  "modified_by": "rlane@example.com",
  "permissions": {
    "metadata": true,
    "get": true,
    "update": true
  }
}

Response Headers

• Content-Type – application/json

Status Codes

• 200 OK – Success

• 403 Forbidden – Client does not have permissions to get the credential for the provided ID.

• 404 Not Found – The provided credential ID does not exist.

PUT /v1/credentials/(id)

Update the provided credential using the data provided in the POST body.

Example request:

PUT /v1/credentials/abcd12345bf4f1cafe8e722d3860404

Parameters

• id (str) – The credential ID to update.

Request JSON Object

• name (string) – The friendly name for the credential.

• Dictionary{string – string} credential_pairs: A dictionary of arbitrary key/value pairs to be encrypted at rest.

• Dictionary{string – string} metadata: A dictionary of arbitrary key/ value pairs for custom per-credential end-user extensions. This is not encrypted at rest.

• enabled (boolean) – Whether or not this credential is enabled.

• documentation (string) – End-user provided documentation for this credential.

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

 {
   "id": "abcd12345bf4f1cafe8e722d3860404",
   "name": "Example Credential",
   "credential_keys": ["example_credential_key"],
   "credential_pairs": {
     "example_credential_key": "example_credential_value"
   },
   "metadata": {
     "example_metadata_key": "example_value"
   },
   "revision": 1,
   "enabled": true,
   "documentation": "Example documentation",
   "modified_date": "2019-12-16T23:16:11.413299+00:00",
   "modified_by": "rlane@example.com",
   "permissions": {
     "metadata": true,
     "get": true,
     "update": true
   }
 }

Response Headers

• Content-Type – application/json

Status Codes

• 200 OK – Success

• 400 Bad Request – Invalid input; either the data provided was not in the correct format, or the update would create conflicting credential keys in a mapped service.

• 403 Forbidden – Client does not have access to update the provided credential ID.

GET /v1/services/(id)/(old_revision)/(new_revision)

Returns a diff between old_revision and new_revision for the provided service id.

Example request:

GET /v1/services/example-development/1/2

Parameters

• id (str) – The service ID to get.

• old_revision (int) – One of the two revisions to diff against.

• new_revision (int) – One of the two revisions to diff against.

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "enabled": {
    "added": true,
    "removed": false
  },
  "credentials": {
    "added": [
      "abcd12345bf4f1cafe8e722d3860404"
    ],
    "removed": [
      "aaaa33335bf4f1cafe8e722d3860404"
    ]
  },
  "blind_credentials": {},
  "modified_date": {
    "added": "2019-12-16T23:16:11.413299+00:00",
    "removed": "2019-11-16T23:16:11.413299+00:00"
  },
  "modified_by": {
    "added": "rlane@example.com",
    "removed": "testuser@example.com"
  }
}

Response Headers

• Content-Type – application/json

Status Codes

• 200 OK – Success

• 403 Forbidden – Client does not have permissions to diff the provided service ID.

• 404 Not Found – The provided service ID or one of the provided revisions does not exist.

PUT /v1/services/(id)/(to_revision)

Revert the provided service to the provided revision.

Example request:

PUT /v1/services/example-development/1

Parameters

• id (str) – The service ID to revert.

• to_revision (int) – The revision to revert this service to.

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "abcd12345bf4f1cafe8e722d3860404",
  "name": "Example Credential",
  "credential_keys": ["test_key"],
  "credential_pairs": {
    "test_key": "test_value"
  },
  "metadata": {
    "example_metadata_key": "example_value"
  },
  "revision": 1,
  "enabled": true,
  "documentation": "Example documentation",
  "modified_date": "2019-12-16T23:16:11.413299+00:00",
  "modified_by": "rlane@example.com",
  "permissions": {}
}

Response Headers

• Content-Type – application/json

Status Codes

• 200 OK – Success

• 400 Bad Request – Invalid input; the update would create conflicting credential keys in the service mapping.

• 403 Forbidden – Client does not have access to revert the provided service ID.

GET /v1/services/(id)

Get a service object from the provided service ID.

Example request:

GET /v1/services/example-development

Parameters

• id (str) – The service ID to get.

Query Parameters

• metadata_only (boolean) – If true, only fetch metadata for this service, and do not respond with decrypted credential pairs in the credential responses.

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "example-development",
  "revision": 1,
  "enabled": true,
  "modified_date": "2019-12-16T23:16:11.413299+00:00",
  "modified_by": "rlane@example.com",
  "account": null,
  "credentials": [
    {
      "id": "abcd12345bf4f1cafe8e722d3860404",
      "name": "Example Credential",
      "credential_keys": ["test_key"],
      "credential_pairs": {
        "test_key": "test_value"
      },
      "metadata": {
        "example_metadata_key": "example_value"
      },
      "revision": 1,
      "enabled": true,
      "documentation": "Example documentation",
      "modified_date": "2019-12-16T23:16:11.413299+00:00",
      "modified_by": "rlane@example.com",
      "permissions": {}
    },
    ...
  ],
  "blind_credentials": [],
  "permissions": {
    "metadata": true,
    "get": true,
    "update": true
  }
}

Response Headers

• Content-Type – application/json

Status Codes

• 200 OK – Success

• 403 Forbidden – Client does not have permissions to get the service ID provided.

PUT /v1/services/(id)

Create or update a service to credential mapping.

Example request:

PUT /v1/services/example-development

Parameters

• id (str) – The service ID to create or update.

Request JSON Object

• credentials (List[string]) – A list of credential IDs to map to this service.

• blind_credentials (List[string]) – A list of blind_credential IDs to map to this service.

• enabled (boolean) – Whether or not this service is enabled. (default: true)

• account (string) – An AWS account to scope this service to.

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "example-development",
  "revision": 1,
  "enabled": true,
  "modified_date": "2019-12-16T23:16:11.413299+00:00",
  "modified_by": "rlane@example.com",
  "account": null,
  "credentials": [
    {
      "id": "abcd12345bf4f1cafe8e722d3860404",
      "name": "Example Credential",
      "credential_keys": ["test_key"],
      "credential_pairs": {
        "test_key": "test_value"
      },
      "metadata": {
        "example_metadata_key": "example_value"
      },
      "revision": 1,
      "enabled": true,
      "documentation": "Example documentation",
      "modified_date": "2019-12-16T23:16:11.413299+00:00",
      "modified_by": "rlane@example.com",
      "permissions": {}
    },
    ...
  ],
  "blind_credentials": [],
  "permissions": {}
    "metadata": True,
    "get": True,
    "update": True
  }
}

Response Headers

• Content-Type – application/json

Status Codes

• 200 OK – Success

• 400 Bad Request – Invalid input; Either required fields were not provided or credentials being mapped would result in credential key conflicts.

• 403 Forbidden – Client does not have permissions to create or update the specified service ID.

PUT /v1/grants/(id)

Ensure grants are set for the provided service ID.

Example request:

PUT /v1/grants/example-development

Parameters

• id (str) – The service ID to ensure grants for.

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "example-development",
  "grants": {
    "encrypt_grant": true,
    "decrypt_grant": true
  }
}

Response Headers

• Content-Type – application/json

Status Codes

• 200 OK – Success

• 400 Bad Request – Invalid input. The service provided does not exist.

• 403 Forbidden – Client does not have permissions to create or update the specified service ID.

GET /v1/grants/(id)

Get grants for the provided service ID.

Example request:

GET /v1/grants/example-development

Parameters

• id (str) – The service ID to ensure grants for.

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "example-development",
  "grants": {
    "encrypt_grant": true,
    "decrypt_grant": true
  }
}

Response Headers

• Content-Type – application/json

Status Codes

• 200 OK – Success

• 400 Bad Request – Invalid input. The service provided does not exist.

• 403 Forbidden – Client does not have permissions to get service metadata for the specified service ID.

GET /v1/cas/(ca)

Get the CA information for the provided ca.

Example request:

GET /v1/cas/example-ca

Parameters

• ca (str) – The friendly name of the certificate authority to issue a certificate against.

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "example-ca": {
    "certificate": "---...BEGIN...",
    "certificate_chain": "---...BEGIN...",
    "tags": {
      "hello": "world"
   }
}

Response Headers

• Content-Type – application/json

Status Codes

• 200 OK – Success

• 403 Forbidden – Client does not have access to get the requested CA.