Introducing Webscale service users

An introduction to Webscale service users

Overview

Webscale service users are a special type of Webscale user. Instead of representing a particular person, service users encapsulate a persistent Webscale API access key, useful for completing long-standing tasks, typically in an automated environment like deployment scripts. Service users are scoped to the account and, as a result, can be managed like any other account-level resource.

Manage service users

Creating, updating and deleting service users can only done directly through the Webscale API.

Create and update

# Creating a service user.
POST /v2/accounts/{account-id}/service-users
{
    "name": ...,
    "description": ...
}

# Updating a service user.
PATCH /v2/accounts/{account-id}/service-users/{user-id}
{
    "name": ...,
    "description": ...
}

To create a service user, provide a name and a meaningful description. To make management easier, it is recommended to include the service user’s responsibilities in the description. These fields can be updated after creation.

After creating a new service user or updating an existing one, the service user is returned:

{
    href: the user's unique API reference,
    name: ...,
    description: ...,
    email: an auto-generated email in the webscalenetworks.com domain,
    account: the account in which the user can be managed,
    access_keys: a collection of access keys granting access to the account,
}

It is important to note the service user’s href, email and access_keys.

  • href is used to update the user.
  • email is used to invite the user to roles and groups.
  • access_keys grants the user permission to the Webscale API. These access keys do not expire, making them useful for long-standing tasks like creating Webscale custom logs from application servers.

Delete

DELETE /v2/accounts/{id}/service-users/{id}

Deleting a service user requires the service user’s ID, which can be retrieved from its href attribute.

Invite service users to roles

Service users can be invited to any roles or groups using their email and the Control Panel.

Once invited, service users can have invitations accepted on their behalf:

# List the service user's pending invitations.
GET /v2/users/{user-id}/invitations

# Accept a specific invitation.
PATCH /v2/users/{user-id}/invitations/{invitation-id}
{
    "state": "accepted"
}

By default these permissions are granted to Account editors.

Authenticate into different accounts

Although service users are created in a specific account, they can authenticate into other accounts as long as they have accepted a role in that account.

To authenticate into a new account:

POST /v2/users/self/authorization
{ "account": <Webscale-account-href> }

which returns a JSON web token (JWT) valid for one day.

To generate a persistent access key from this account:

POST /v2/users/self/access-keys
{ "type": "bearer" }

Last modified October 27, 2022