API Auth

There are two ways to authenticate against the DCE APIs:

  1. AWS Cognito
  2. IAM credentials



Admins have full access to all APIs and will not get back filtered results when querying APIs.

There are three different ways a user is considered an admin:

  1. They have an IAM user/role/etc with a policy that gives them access to the API
  2. A Cognito user is placed into a Cognito group called Admins
  3. A Cognito user has an attribute in custom:roles that will match a search criteria specified by the Terraform variable cognito_roles_attribute_admin_name


Users are given access to the leases and usage APIs. This is done so they can request their own lease and look at the usage of their leases. Any user authenticated through Cognito will automatically fall into the Users role unless designated as an Admin.

Using AWS Cognito

AWS Cognito is used to authenticate and authorize DCE users. This section will walk through setting this up in the AWS web console, but note that all of these operations can be automated using the AWS CLI or SDKs. While this example uses Cognito User Pools to create and manage users, you may also integrate Cognito with your own IdP.

Configuring Cognito

  1. Open the AWS Console in your DCE Master Account and Navigate to AWS Cognito by typing Cognito in the search bar

  2. Select Manage User Pools and click on the dce user pool.

    Manage user pools
  3. Select Users and groups

    Users and Groups
  4. Create a user

    Create User
  5. Name the user and provide a temporary password. You may uncheck all of the boxes and leave the other fields blank. This user will not have admin priviliges.

    Quick start user
  6. Create a second user to serve as a system admin. Follow the same steps as you did for creating the first user, but name this one something appropriate for their role as an administrator.

    Quick start admin
  7. Create a group

    Create group
  8. Users in this group will be granted admin access to DCE. The group name must contain the term Admin. Choose a name and click on the Create group button.

    Group name
  9. Add your admin user to the admin group to grant them admin privileges.

    Quick start admin detail Add to group
  10. Type dce auth in your command terminal. This will open a browser with a log in screen. Enter the username and password for the non-admin user that you created. Reset the password as prompted.

    Quick start user login
  11. Upon successfully logging in, you will be redirected to a credentials page containing a temporary authentication code. Click the button to copy the auth code to your clipboard.

    Credentials Page
  12. Return to your command terminal and paste the auth code into the prompt.

    dce auth
    ✔ Enter API Token: : █
  13. You are now authenticated as a DCE User. Test that you have proper authorization by typing dce leases list. This will return an empty list indicating that there are currently no leases which you can view. If you are not properly authenticated as a user, you will see a permissions error.

    dce leases list
  14. Users are not authorized to list child accounts in the accounts pool. Type dce accounts list to verify that you get a permissions error when trying to view information you do not have access to.

    dce accounts list
    err:  [GET /accounts][403] getAccountsForbidden

Using IAM Credentials

The DCE API accepts authentication via IAM credentials using SigV4 signed requests.

At minumum, the IAM credentials used to access DCE must have an attached policy that grants permission to invoke the DCE API Gateway methods, e.g.

  "Version": "2012-10-17",
  "Statement": [
      "Effect": "Allow",
      "Action": [
      "Resource": [
        "<DCE API Gateway ARN>"

This policy is accessible via the api_access_policy_name and api_access_policy_arn terraform outputs.

Any requests made with IAM credentials that have sufficient permissions to invoke the DCE API, but which are not associated with a Congito User Pool User, will be treated as an admin role.

The process for signing requests with SigV4 is somewhat involved, but luckily there are a number of tools to make this easier. For example:

AWS also provides examples for a number of languages in their docs.

See DCE CLI Credentials to configure IAM credentials for the DCE CLI.