Admin Logic Version 1 API reference

This is the reference for Adjutant when it is using the default configuration. Different deployments may exclude certain task views or include their own additional ones.

The core functionality of Adjutant is built around the concept of tasks and actions.

Actions are both concepts in the database and code that can execute whatever logic is necessary at each stage.

Tasks can bundle a number of actions and have 3 main steps.

  1. A user submits a request to the specified endpoint.

  2. An admin approves the request, or it is automatically approved. At this point the admin can also update invalid data inside the task.

  3. If necessary a user will be emailed a token and will submit additional data (ie passwords or a confirmation) to finish the task.

Depending on the task and the data provided some steps may be skipped.

Authentication

The ‘X-Auth-Token’ header value should be provided for authentication with a valid Keystone token.

HTTP Status Codes

Success

Code

Reason

200 - OK

Request was successful.

200 - OK

Request successful, task submitted.

202 - Accepted

Request is accepted, but processing may take some time.

Error

Code

Reason

400 - Bad Request

Bad request

401 - Unauthorized

User is unauthenticated, or X-Auth-Token has expired.

403 - Forbidden

User has the wrong roles for this operation.

404 - Not Found

The requested resource could not be found.

405 - Method Not Allowed

Method is not valid for this endpoint and resource.

409 - Conflict

Conflict

500 - Internal Server Error

Something went wrong with the service which prevents it from fulfilling the request.

503 - Service Unavailable

Adjutant cannot connect to the Keystone Authentication Server.

Service Discovery

GET
/

Version Discovery Endpoint

Unauthenticated.

JSON containing details of the currently available versions (just v1 for now)

Normal response code: 200

GET
/v1

Version One Details Endpoint

Unauthenticated.

Details V1 version details and the available taskviews and their fields. See below for further details on the individual taskviews.

Normal response code: 200

Administrative Endpoints

Endpoints for the management of tasks, tokens, and notifications. Most of these are limited by roles, or are for admin use only.

GET
/v1/status

Status

Authentication: Administrator

Normal Response Code: 200

Simple status endpoint.

Returns a list of unacknowledged error notifications, and both the last created and last completed tasks.

GET
/v1/tasks

List Tasks

Authentication: Administrator

Normal Response Codes: 200

Error Response Codes: 401, 403

Lists all tasks.

Name

In

Type

Description

filters (Optional)

query

dictionary

Django style filters for task, token and notification endpoints. See section Filters for details.

page (Optional)

query

int

Page number to access, starts at and defaults to 1.

tasks_per_page (Optional)

query

int

Limit on the tasks viewed on each page.

Request Example

curl -H "X-Auth-Token: $OS_TOKEN" http://adjutant/v1/tasks

Response Example

{
    "tasks": [
        {
            "action_notes": {
                "ResetUserPasswordAction": [
                    "Existing user with matching email.",
                ]
            },
            "actions": [
                {
                    "action_name": "ResetUserPasswordAction",
                    "data": {
                        "domain_name": "Default",
                        "email": "demo@example.com"
                    },
                    "valid": true
                }
            ],
            "approved": true,
            "approved_by": {},
            "approved_on": "2017-08-30T21:29:48.484441Z",
            "cancelled": false,
            "completed": true,
            "completed_on": "2017-08-30T21:30:13.269498Z",
            "created_on": "2017-08-30T21:29:47.989851Z",
            "ip_address": "127.0.0.1",
            "keystone_user": {},
            "project_id": null,
            "task_type": "reset_password",
            "uuid": "d5c7901cfecd45ec9a87871035c9f662"
        },
        {
        "action_notes": {
            "NewProjectDefaultNetworkAction": [],
            "NewProjectWithUserAction": [],
            "SetProjectQuotaAction": []
        },
        "actions": [
            {
                "action_name": "NewProjectWithUserAction",
                "data": {
                    "domain_id": "default",
                    "email": "test@example.com",
                    "parent_id": null,
                    "project_name": "test_project"
                },
                "valid": true
            },
            {
                "action_name": "NewProjectDefaultNetworkAction",
                "data": {
                    "region": "RegionOne",
                    "setup_network": false
                },
                "valid": true
            },
            {
                "action_name": "SetProjectQuotaAction",
                "data": {},
                "valid": true
            }
        ],
        "approved": false,
        "approved_by": {},
        "approved_on": None,
        "cancelled": false,
        "completed": false,
        "completed_on": null,
        "created_on": "2017-07-26T21:44:21.082248Z",
        "ip_address": "127.0.0.1",
        "keystone_user": {},
        "project_id": null,
        "task_type": "signup",
        "uuid": "370d952c63ba410c8704abc12cfd97b7"
    }
}
GET
/v1/tasks/

Task Details

Authentication: Administrator

Normal Response Codes: 200

Error Response Codes: 401, 403, 404

Gives details for the specific task.

Name

In

Type

Description

task_id

path

string

The task UUID as given in the task list and email correspondence.

Request Example

curl -H "X-Auth-Token: $OS_TOKEN" http://adjutant/v1/tasks/d5c7901cfecd45ec9a87871035c9f662

Response Example

{
    "action_notes": {
        "ResetUserPasswordAction": [
            "Existing user with matching email.",
        ]
    },
    "actions": [
        {
            "action_name": "ResetUserPasswordAction",
            "data": {
                "domain_name": "Default",
                "email": "demo@example.com"
            },
            "valid": true
        }
    ],
    "approved": true,
    "approved_by": {},
    "approved_on": "2017-08-30T21:29:48.484441Z",
    "cancelled": false,
    "completed": true,
    "completed_on": null,
    "created_on": "2017-08-30T21:29:47.989851Z",
    "ip_address": "127.0.0.1",
    "keystone_user": {},
    "project_id": null,
    "task_type": "reset_password",
    "uuid": "d5c7901cfecd45ec9a87871035c9f662"
}
PUT
/v1/tasks/

Update Task

Authentication: Project Admin or Project Moderator

Normal Response Codes: 200

Error Response Codes: 400, 401, 403, 404

Replace the data in an unapproved action and rerun the preapproval steps

Name

In

Type

Description

task_data

body

dictionary

A dictionary replacing all the data for a task. See the task details for what values should be included

Request Example

curl -H "X-Auth-Token: $OS_TOKEN" \
    -H 'Content-Type: application/json' \
    -X PUT --data '{
        "project_name": "a_project",
        "email": "example.a@t.com",
        "region": "RegionOne",
        "setup_network": false
      }' http://0.0.0.0:5050/v1/tasks/19dbe418ecc14aeb94053f23eda01c78

Response Example

{
  "notes": ["Task successfully updated."]
}
POST
/v1/tasks/

Approve Task

Authentication: Administrator

Normal Response Codes: 200

Error Response Codes: 400, 401, 403, 404

Approves a task and runs the actions approval steps.

Name

In

Type

Description

task_id

path

string

The task UUID as given in the task list and email correspondence.

approved

body

boolean

Confirmation to approve a task.

Request Example

curl -H "X-Auth-Token: $OS_TOKEN" -H 'Content-Type: application/json' \
      -d '{"approved": true}' http://0.0.0.0:5050/v1/tasks/19dbe418ecc14aeb94053f23eda01c78

Response Example

{
  "notes": ["Created Token."]
}

In most cases an email will be sent after approval to the user who requested the task.

DELETE
/v1/tasks/

Cancel Task

Authentication: Administrator, Project Admin or Project Moderator

Normal Response Codes: 200

Error Response Codes: 400, 401, 403, 404

Cancel a task. Tasks can be cancelled at any stage prior to their completion, an issued token for a cancelled task will be invalidated.

Project Admins and Project Moderators can only cancel tasks associated with their projects.

Name

In

Type

Description

task_id

path

string

The task UUID as given in the task list and email correspondence.

GET
/v1/tokens

List tokens

Authentication: Administrator

Normal Response Codes: 200

Error Response Codes: 401, 403

List all active tokens.

Name

In

Type

Description

filters (Optional)

query

dictionary

Django style filters for task, token and notification endpoints. See section Filters for details.

POST
/v1/tokens

Reissue Tokens

Authentication: Administrator, Project Admin or Project Moderator

Normal Response Codes: 200

Error Response Codes: 400, 401, 403, 404

Reissue a token for the specified task.

Name

In

Type

Description

task_id

body

int

The task UUID as given in the task list and email correspondence.

DELETE
/v1/token

Delete Expired Tokens

Authentication: Administrator

Normal Response Codes: 200

Error Response Codes: 401, 403

Delete all expired tokens.

Note that if a token has expired it will be deleted when someone attempts to access it, this will prevent the database from clogging up however will not have an effect on functionality.

GET
/v1/token/

Get Token Details

Authentication: Unauthenticated

Normal Response Codes: 200

Error Response Codes: 401, 403, 404

Details the actions, task_type and required fields of the token

Name

In

Type

Description

token_id

path

string

The token UUID, as given on the lists and in email correspondence.

Request Example

curl http://0.0.0.0:5050/v1/tokens/771af33fb28e46aab45e265bd6a6d469

Response Example

{
  "actions": [
      "NewProjectWithUserAction",
      "NewProjectDefaultNetworkAction",
      "SetProjectQuotaAction"
  ],
  "required_fields": [
      "password"
  ],
  "task_type": "signup"
}
POST
/v1/token/

Submit Token

Authentication: Unauthenticated

Normal Response Codes: 200

Error Response Codes: 400, 404

Submit a token and it’s data to the last stage of an action execution. A 400 will be return if it does not contain all of the necessary fields.

Name

In

Type

Description

token_id

path

string

The token UUID, as given on the lists and in email correspondence.

token_data

body

dictionary

A dictionary replacing all the data for a task. Use the token get request to see what should needs to be included.

Request Example

curl -H 'Content-Type: application/json' \
     -d '{"password": "12345"}' http://0.0.0.0:5050/v1/tokens/771af33fb28e46aab45e265bd6a6d469

Response Example

{"notes":["Token submitted successfully."]}

In most cases an email will be sent after token submission, detailing what has changed.

GET
/v1/notification

List Notifications

Authentication: Administrator

Normal Response Codes: 200

Error Response Codes: 401, 403

List all unacknowledged notifications

Name

In

Type

Description

filters (Optional)

query

dictionary

Django style filters for task, token and notification endpoints. See section Filters for details.

POST
/v1/notification

Acknowledge a List of Notifications

Authentication: Administrator

Mark a given list of notifications as acknowledged

Name

In

Type

Description

notifications

body

array

List of notification UUIDs to acknowledge

GET
/v1/notification/

Notification Details

Get details of a specific notification

Name

In

Type

Description

notification_id

path

string

The notification UUID, as given on list endpoints and in email correspondence.

GET
/v1/notification/

Acknowledge Notification

Acknowledge a specific notification.

Name

In

Type

Description

notification_id

path

string

The notification UUID, as given on list endpoints and in email correspondence.

acknowledged

body

boolean

Confirmation for acknowledging a notification.

Filtering Tasks, Tokens, and Notifications

The task, token, and notification list endpoints can be filtered using a slight variant of the Django ORM filters.

This is done but sending a json with filters via HTTP parameters:

{'filters': {'fieldname': { 'operation': 'value'}}

Example:

{'filters': {'task_id': { 'exact': '842433bb-fa08-4fc1-8c3b-aa9904ceb370'}}

This looks a bit messy in the url as that json ends up being url-safe encoded, but doing the filters this way gives us a fairly large amount of flexibility.

Possible field lookup operations: https://docs.djangoproject.com/en/1.11/ref/models/querysets/#id4

OpenStack Style TaskView Endpoints

A response of ‘task created’ means that the task requires admin approval and a response of ‘created token’ indicates that the task has been auto-approved and awaits the submission of an emailed token.

GET
/v1/openstack/users

List users

Authentication: Project Moderator or Admin

List current and pending users in the current project.

Request Example

curl -H "X-Auth-Token: $NOS_TOKEN" http://0.0.0.0:5050/v1/openstack/users

Response Example

{
    "users": [
        {
            "cohort": "Member",
            "email": "demo@example.com",
            "id": "",
            "manageable": false,
            "name": "demo",
            "roles": [
                "project_admin",
                "__member__"
            ],
            "status": "Active"
        }
    ]
}
POST
/v1/openstack/users

Invite User

Authentication: Project Moderator or Admin

An auto-approved task that will add a user to the project. If the user already exists it will add them directly, otherwise it will create a user when the invitee submits a token sent to them though email

Name

In

Type

Description

roles

body

array

List of roles for the user.

email

body

string

New user email address.

username (Optional)

body

string

New user username, required only if USERNAME_IS_EMAIL is false.

Request Example

curl -H "X-Auth-Token: $NOS_TOKEN" http://0.0.0.0:5050/v1/openstack/users \
 -H 'Content-Type: application/json' \
-d '{"roles": ["_member_"], "email": "new@example.com"}'

Response Example

{
  "notes": ["created token"]
}
GET
/v1/openstack/users/

User Details

Authentication: Project Moderator or Admin

Get details on the given user including their roles on your project

Name

In

Type

Description

user_id

path

string

The user id, as seen on the ../v1/openstack/users page. Note that this is the openstack user id for confirmed users and the task ID for invited users.

DELETE
/v1/openstack/users/

Cancel User Invite

Authentication: Project Moderator or Admin

Cancel a pending user invitation. Current users can be removed from your project by removing all of their roles.

Name

In

Type

Description

user_id

path

string

The user id, as seen on the ../v1/openstack/users page. Note that this is the openstack user id for confirmed users and the task ID for invited users.

GET
/v1/openstack/users//roles

List User Roles

Authentication: Project Moderator or Admin

List all roles the user has on the current project

Name

In

Type

Description

user_id

path

string

The user id, as seen on the ../v1/openstack/users page. Note that this is the openstack user id for confirmed users and the task ID for invited users.

PUT
/v1/openstack/users//roles

Add User Roles

Authentication: Project Moderator or Admin

Add the specified roles to the user on the current project.

There is additional authentication in the forms of what roles can be edited by the current user. If the target user has any role not editable by the current user the user will not be able to edit any of their roles. Editiable roles can be found at the List available roles endpoint.

Name

In

Type

Description

user_id

path

string

The user id, as seen on the ../v1/openstack/users page. Note that this is the openstack user id for confirmed users and the task ID for invited users.

roles

body

array

List of roles for the user.

Request Example

curl -H "X-Auth-Token: $NOS_TOKEN" -H 'Content-Type: application/json' \
-d '{"roles": ["project_mod"]}' -X PUT \
http://0.0.0.0:5050/v1/openstack/users/5123ca764f3d40d79e3589e91f1ccb8f/roles

Response Example

{
    "notes": [
        "Task completed successfully."
    ]
}
DELETE
/v1/openstack/users//roles

Remove User Roles

Authentication: Project Moderator or Admin

Remove the specified roles from the user on the current project.

A project moderator will not be able to change the roles of a project admin.

Name

In

Type

Description

user_id

path

string

The user id, as seen on the ../v1/openstack/users page. Note that this is the openstack user id for confirmed users and the task ID for invited users.

roles

body

array

List of roles for the user.

Request Example

curl -H "X-Auth-Token: $NOS_TOKEN" -H 'Content-Type: application/json' \
-d '{"roles": ["project_mod"]}' -X DELETE \
http://0.0.0.0:5050/v1/openstack/users/5123ca764f3d40d79e3589e91f1ccb8f/roles

Response Example

{
    "notes": [
        "Task completed successfully."
    ]
}
GET
/v1/openstack/roles

List Available Roles

Authentication: Project Moderator or Admin

List the roles available for the current user to modify.

Request Example

curl -H "X-Auth-Token: $NOS_TOKEN" http://0.0.0.0:5050/v1/openstack/roles/

Response Example

{
    "roles": [
        {
            "domain_id": null,
            "id": "b81efc1e23a043d0976dc39b3e2727c3",
            "links": {
                "self": "http://identity/v3/roles/b81efc1e23a043d0976dc39b3e2727c3"
            },
            "name": "project_mod"
        },
        {
            "domain_id": null,
            "id": "9fe2ff9ee4384b1894a90878d3e92bab",
            "links": {
                "self": "http://identity/v3/roles/9fe2ff9ee4384b1894a90878d3e92bab"
            },
            "name": "_member_"
        },
    ]
}
POST
/v1/openstack/users/password-reset

Password Reset

Authentication: Unauthenticated

Unauthenticated for forgotten password requests. If the email has an associated user a token will be sent to them to use to reset their password with.

Name

In

Type

Description

email

body

string

Email address for the user whose password needs resetting

username (Optional)

body

string

Username, required only if USERNAME_IS_EMAIL is false.

Request Example

curl -d '{"email": "demo@example.org"}' http://0.0.0.0:5050/v1/openstack/users/password-reset

Response Example

{
  "notes": ["If user with email exists, reset token will be issued."]
}
POST
/v1/openstack/email-update

Update Email Address

Authentication: Authenticated

Submit a new email address for the current user. A submission token will be sent to the new address, and a notification to the old email address. The account address will not change until the token submission.

Name

In

Type

Description

email

body

string

New user email address.

POST
/v1/openstack/sign-up

Sign Up

Authentication: Unauthenticated

Account creation endpoint.

Name

In

Type

Description

email

body

string

New user email address.

username (Optional)

body

string

New user username, required only if USERNAME_IS_EMAIL is false.

project_name

query

string

Name for the new project.

setup_network

query

boolean

Whether or not to setup a default network for a new project

region

query

string

Region to perform actions in.

Request Example

curl -H 'X-Auth-Token: $OS_TOKEN' -H 'Content-Type: application/json' -d '{
    "email": "example@example.com", "project_name": "example_project"}'
    -X POST  http://0.0.0.0:5050/v1/openstack/sign-up

Response Example

{
  "notes": ["task created"]
}
GET
/v1/openstack/quota

Show Quota Details

Authentication: Project Moderator or Admin

List details of the quota for the current project.

Name

In

Type

Description

region

query

string

Region to perform actions in.

Request Example

curl -H "X-Auth-Token: $NOS_TOKEN" http://0.0.0.0:5050/v1/openstack/quota

Response Example

{
    "active_quota_tasks": [],
    "quota_size_order": [
        "small",
        "medium",
        "large"
    ],
    "quota_sizes": {
        "large": {
            "cinder": {
                "gigabytes": 50000,
                "snapshots": 600,
                "volumes": 200
            },
            "neutron": {
                "floatingip": 50,
                "network": 10,
                "port": 500,
                ...
            },
            "nova": {
                "cores": 200,
                "fixed_ips": 0,
                "floating_ips": 50,
                "injected_file_content_bytes": 10240,
                ...
            }
        },
        'small': { ... },
        'medium': { ... }
    },
    "regions": [
        {
            "current_quota": {
                "cinder": {
                    "backup_gigabytes": 1000,
                    "backups": 10,
                    "gigabytes": 1000,
                    ...
                },
                "neutron": {
                    "floatingip": 50,
                    "network": 10,
                    "port": 50,
                    ...
                },
                "nova": {
                    "cores": 20,
                    "fixed_ips": -1,
                    "floating_ips": 10,
                    "injected_file_content_bytes": 10240,
                    ...
                }
            },
            "current_quota_size": "custom",
            "current_usage": {
                "cinder": {
                    "gigabytes": 1,
                    "snapshots": 0,
                    "volumes": 1
                },
                "neutron": {
                    "floatingip": 0,
                    "network": 1,
                    "port": 2,
                    "router": 1
                    ...
                },
                "nova": {
                    "cores": 0,
                    "floating_ips": 0,
                    ...
                }
            },
            "quota_change_options": [],
            "region": "RegionOne"
        }
    ]
}
POST
/v1/openstack/quota

Update Quota

Authentication: Project Moderator or Admin

Starts an update quota task. If regions are not specified it will update the quota across all regions.

Name

In

Type

Description

regions (Optional)

body

array

Regions to perform actions in.

size

body

string

Which size out of the selections shown in the quota get request should the region(s) be updated to.

Request Example

curl -H "X-Auth-Token: $NOS_TOKEN" http://0.0.0.0:5050/v1/openstack/quotas
  -d '{"region": "RegionOne", "size": "small"}' -H "Content-Type: application/json"

Response Example

{
  "notes": ["Task processed. Awaiting Aprroval."]
}

Additional API Documentation

While in debug mode the service will supply online browsable documentation via Django REST Swagger.

This is viewable at: ../docs