Versions Compared

Version Old Version 3 New Version 4
Changes made by

Alvaro de la Serna Martinez

Alvaro de la Serna Martinez

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Table of Contents
minLevel2
maxLevel2
outlinefalse
typeflat
separatorbrackets
printabletrue

Overview

Check the list of available endpoints and methods to create and modify users using the Provisioning API.

...

Endpoints and methods

...

Description

...

Status
colourYellow
titleGET
 /v2/accounts/{accountName}/tokens see below

...

Get a list of all the tokens for the provided account.

...

Status
colourYellow
titleGET
/v2/accounts/{accountName}/tokens/{tokenId} see below

...

Returns all the information of a single token, including the actual token.

...

Status
colourGreen
titlePOST
/v2/accounts/{accountName}/tokens see below

...

Create a new token.

...

Status
colourBlue
titlePUT
/v2/accounts/{accountName}/tokens/{tokenId}/enable see below

...

Enable a token.

...

Status
colourBlue
titlePUT
/v2/accounts/{accountName}/tokens/{tokenId}/disable see below

...

Disable a token.

...

Status
colourBlue
titlePUT
/v2/accounts/{accountName}/tokens/{tokenId}/rename see below

...

Change the name associated with a token.

...

Status
colourRed
titleDELETE
/v2/accounts/{accountName}/tokens/{tokenId} see below

...

Delete a token.

Endpoints and methods

...

Lists all the tokens for the provided account. This endpoint returns the information about the tokens and their IDs, but NOT the tokens themselves for security.

...

titleRequest

Path parameters

Add the following path parameters as part of the endpoint:

...

Parameter

...

Type

...

Description

...

accountName required

...

string

...

The name of the account.

Find below a request example:

Code Block
https://api-us.devo.com/xxx/v2/accounts/sampleAccount/tokens

...

titleResponse

...

Code

...

Description

...

200

...

Successful response. List of tokens retrieved.

Code Block
[
  {
    "name": "a",
    "id": 1,
    "scope": "table://*.** level://admin",
    "owner": "web-testing+auto-admin@devo.com",
    "user": "web-testing+auto-admin@devo.com",
    "audience": "apiv2-admin aggregations apiv2",
    "token_type": "Bearer",
    "active": true,
    "expiration": "2024-11-26T14:38:18.000+0000",
    "account": "autotest",
    "created": "2024-11-25T14:38:18.000+0000",
    "updated": "2024-11-25T14:38:18.000+0000",
    "expires_in_seconds": 86400
  },
  {
    "name": "b",
    "id": 2,
    "scope": "table://*.** level://admin",
    "owner": "web-testing+auto-admin@devo.com",
    "user": "web-testing+auto-admin@devo.com",
    "audience": "apiv2-admin aggregations apiv2",
    "token_type": "Bearer",
    "active": true,
    "expiration": "2024-11-26T14:38:18.000+0000",
    "account": "autotest",
    "created": "2024-11-25T14:38:18.000+0000",
    "updated": "2024-11-25T14:38:18.000+0000",
    "expires_in_seconds": 86400
  }
]

...

4xx

...

Bad request.

Code Block
{
  "error": {
    "code": 4xx,
    "message": "string"
  }
}
Table of Contents
minLevel2
maxLevel2
outlinefalse
typeflat
separatorbrackets
printabletrue

Overview

Check the list of available endpoints and methods to create and modify users using the Provisioning API.

Endpoints and methods

Description

Status
colourYellow
titleGET
 /v2/accounts/{accountName}/tokens see below

Get a list of all the tokens for the provided account.

Status
colourYellow
titleGET
/v2/accounts/{accountName}/tokens/{tokenId} see below

Returns all the information of a single token, including the actual token.

Status
colourGreen
titlePOST
/v2/accounts/{accountName}/tokens see below

Create a new token.

Status
colourBlue
titlePUT
/v2/accounts/{accountName}/tokens/{tokenId}/enable see below

Enable a token.

Status
colourBlue
titlePUT
/v2/accounts/{accountName}/tokens/{tokenId}/disable see below

Disable a token.

Status
colourBlue
titlePUT
/v2/accounts/{accountName}/tokens/{tokenId}/rename see below

Change the name associated with a token.

Status
colourRed
titleDELETE
/v2/accounts/{accountName}/tokens/{tokenId} see below

Delete a token.

Endpoints and methods

Anchor
path1
path1
GET /v2/accounts/{accountName}/tokens

...

Lists all the tokens for the provided account. This endpoint returns the information about the tokens and their IDs, but NOT the tokens themselves for security.

The ID of the token
Expand
titleRequest

Path parameters

Add the following path parameters as part of the endpoint:

Parameter

Type

Description

accountName required

string

The name of the account

.

tokenId required

string

.

Find below a request example:

Code Block
https://api-us.devo.com/xxx/v2/accounts/sampleAccount/tokens/3

Bad request.

{
Expand
titleResponse

Code

Description

200

Successful response. List of tokens retrieved.

Code Block
[
  {
    "name": "
test
a",
    "id":
3
1,
    "scope": "table://*.** level://admin",
    "owner": "web-testing+auto-admin@devo.com",
    "user": "web-testing+auto-admin@devo.com",
    "audience": "apiv2-admin aggregations apiv2",
    "token_type": "Bearer",
    "active": true,
    "expiration": "2024-11-26T14:38:18.000
+0000", "token": "31089320378051f1a2ee17c14028f056",
+0000",
    "account": "sampleAccount",
    "created": "2024-11-25T14:38:18.000+0000",
    "updated": "2024-11-25T14:38:18.000+
0000",
0000",
    "expires_in_seconds": 86400
  },
  {
    "name": "b",
    "id": 2,
    "
expires_in_seconds": 86400 }

4xx

Code Block
scope": "table://*.** level://admin",
    "
error
owner":
{
"web-testing+auto-admin@devo.com",
    "
code
user":
4xx
"web-testing+auto-admin@devo.com",
    "
message
audience": "
string"
apiv2-admin aggregations apiv2",
} }

...

Add an internal user to a multitenant domain.

Every user in a domain needs to have at least one role assigned to them, either one of the default roles in the application or a custom role. While creating users in a domain, keep in mind the following restrictions:

  • Internal users cannot be used immediately after creation - they must first be activated through a link sent to the email address provided. The activation process also requires the user to create a password.

  • The first user added to a new domain must be internal and must be the domain owner. Owners cannot be deleted, and a domain can only have one owner.

Note

You’ll need the multitenant API keys to create the first user in the domain, and its role must be OWNER. Check an example of this below.

  • To assign a user (new or existing) as a domain owner, use the role OWNER when creating the user. This will create the user with the role ADMIN but with OWNER privileges. The ADMIN role is exclusive and cannot be combined with other roles.

Note

Notice that even though the role OWNER is used to assign a user the ownership of a domain, this is interpreted as ADMIN role, flagged as OWNER, so the actual role (for policies, permissions…) is actually ADMIN, and that value will be returned in the responses (along with a boolean OWNER flag).

  • This method can be also used to add an existing user to a different domain. In this case, the user will keep their original user name and phone number, ignoring any new value provided for them. The field externalId is ignored too since it only has meaning for external users (who might not have a password in the platform).

Query string parameters

Query string parameters are added after the path parameters, preceded by a question mark (?) and separated by an ampersand (&)

Request body

The request JSON body must include the userInfo object with the following key-value pairs:

Find below a request example:

Expand
titleRequest

Parameter

Type

Description

skipMailValidation required

boolean

Set this to true to skip the email address validation step when creating a user for the domain. In this case, the user must already exist in the platform and therefore already have a password. Default value is false.

Note

Note that in order to use this parameter, you must use multitenant domain credentials to authorize your request.

Parameter

Type

Description

domain required

string

Domain name. Must match the expression "^[A-Za-z]A-Za-z0-9_-?$".

userName required

string

Name of the new user. Must match the expression "^(([a-zA-Z0-9À-ÿ])+([ _'.@-]))([a-zA-Z0-9À-ÿ])$".

This field will be ignored if you are adding an already existing user to a different domain, and the current value will be kept.

email required

string

Enter the email address of the new user.

role required

string

Role of the new user. Basic roles in Devo are:

  • OWNER

  • ADMIN

  • NO_PRIVILEGES

Custom roles must match the expression "^(([a-zA-Z0-9])+([ _-]))([a-zA-Z0-9])$".

Check more info about roles at the top of this endpoint section.

phone

string

Phone number of the new user. Must match the expression "^+(?:[0-9] ?){6,14}[0-9]$".

This field will be ignored if you are adding an already existing user to a different domain, and the current value will be kept.

Code Block
https://api-us.devo.com/probio/user/internal?skipValidation=false

And this is an example of a request body, including the required JSON object. In this example, we are adding the first user (owner) of a domain:

Code Block
{
  "domain": "domainName@resellerName",
  "userName": "Frank",
  "email": "user@devo.com",
  "role": "OWNER"
}
Expand
titleResponse

Code

Description

200

Successful response. User added to the given domain.

Code Block{ "email": "user@devo.com", "userName": "Frank", "role": "ADMIN", "domain": "domainName@resellerName", "owner": true, "status": "pending", "roleList": [ "ADMIN" ] 
  "token_type": "Bearer",
    "active": true,
    "expiration": "2024-11-26T14:38:18.000+0000",
    "account": "sampleAccount",
    "created": "2024-11-25T14:38:18.000+0000",
    "updated": "2024-11-25T14:38:18.000+0000",
    "expires_in_seconds": 86400
  }
]

4xx

Bad request.

Code Block
{
  "error": {
    "code": 4xx,
    "message": "string"
  }
}

...

Anchor
path1
path1
GET /v2/accounts/{accountName}/tokens/{tokenId}

Returns the full information on a single token, identified by its ID. The response to this request includes the actual token.

Expand
titleRequest

Path parameters

Add the following path parameters as part of the endpoint:

Parameter

Type

Description

accountName required

string

The name of the account.

tokenId required

string

The ID of the token.

Find below a request example:

Code Block
https://api-us.devo.com/xxx/v2/accounts/sampleAccount/tokens/3
Expand
titleResponse

Code

Description

200

Successful response. Token retrieved.

Code Block
{
  "name": "test",
  "id": 3,
  "scope": "table://*.** level://admin",
  "owner": "web-testing+auto-admin@devo.com",
  "user": "web-testing+auto-admin@devo.com",
  "audience": "apiv2-admin aggregations apiv2",
  "token_type": "Bearer",
  "active": true,
  "expiration": "2024-11-26T14:38:18.000+0000",
  "token": "31089320378051f1a2ee17c14028f056",
  "account": "sampleAccount",
  "created": "2024-11-25T14:38:18.000+0000",
  "updated": "2024-11-25T14:38:18.000+0000",
  "expires_in_seconds": 86400
}

4xx

Bad request.

Code Block
{
  "error": {
    "code": 4xx,
    "message": "string"
  }
}

...

Anchor
path2
path2
POST/v2/accounts/{accountName}/tokens

Creates a new token.

Payload:

Code Block
{
  "name": "string",
  "owner": "email",
  "user": "email",
  "audience": "string",
  "scopes": "string",
  "expiresInSeconds": 86400
}

  • name is optional, and defaults to 'Unnamed' when not present.

  • user is optional and only required when a user is creating a token on behalf of another user. The credentials are resolved for the value of this field (which defaults to the owner when not present).

  • audience is required (samples: apiv2, apiv2-admin, alerts, aggregations, http).

  • scopes is optional and defaults to 'default' when not present.

  • expiresInSeconds is optional and defaults to 86400 when not present. Use the value -1 to create a permanent token.

Expand
titleRequest

Path parameters

Add the following path parameters as part of the endpoint:

Parameter

Type

Description

accountName required

string

The name of the account.

Find below a request example:

Code Block
https://api-us.devo.com/xxx/v2/accounts/sampleAccount/tokens
Expand
titleResponse

Code

Description

200

Successful response. Token created.

Code Block
{
  TBD
}

4xx

Bad request.

Code Block
{
  "error": {
    "code": 4xx,
    "message": "string"
  }
}
Info

Creating a token returns the location header with the URI where the resource can be located.

...

Anchor
path11
path11
PUT/user/email/{userEmail}/domain/{domainName}/role

Set the roles of a user in a given domain.

Expand
titleRequest

Path parameters

Add the following path parameters as part of the endpoint:

Parameter

Type

Description

userEmail required

string

Enter the email of the required user.

domainName required

string

Enter the name of the required domain. You must enter the full domain name using the format {domainName}@{resellerName}

Query string parameters

Query string parameters are added after the path parameters, preceded by a question mark (?) and separated by an ampersand (&)

Parameter

Type

Description

keepExisting

boolean

Set this to true to keep the current roles of the user, plus the new ones added through this request. The default value is false.

Request body

The request JSON body must include the following key-value pairs:

Parameter

Type

Description

roles required

object

Enter the list of role names separated by commas. Basic roles in Devo are:

  • OWNER

  • ADMIN

  • NO_PRIVILEGES

Custom roles must match the expression "^(([a-zA-Z0-9])+([ _-]))([a-zA-Z0-9])$".

Find below a request example:

Code Block
https://api-us.devo.com/probio/user/email/user@devo.com/domain/domainName@resellerName/role?keepExisting=true

And this is an example of a request body, including the required JSON object:

Code Block
[
  "role1", "role2", "role3"
]
Expand
titleResponse

Code

Description

200

Successful response. Roles updated.

4xx

Bad request.

Code Block
{
  "error": {
    "code": 4xx,
    "message": "string"
  }
}

...

Anchor
path15
path15
DELETE/user/email/{userEmail}/domain/{domainName}/role

Removes the indicated roles from the user in the specified domain.

Expand
titleRequest

Path parameters

Add the following path parameters as part of the endpoint:

Parameter

Type

Description

userEmail required

string

Enter the email of the required user.

domainName required

string

Enter the name of the required domain. You must enter the full domain name using the format {domainName}@{resellerName}

Request body

The request JSON body must include the following key-value pairs:

Parameter

Type

Description

roles required

object

List of role names to be deleted, separated by commas. Basic roles in Devo are:

  • OWNER

  • ADMIN

  • NO_PRIVILEGES

Custom roles must match the expression "^(([a-zA-Z0-9])+([ _-]))([a-zA-Z0-9])$".

Find below a request example:

Code Block
https://api-us.devo.com/probio/user/email/user@devo.com/domain/domainName@resellerName/role

And this is an example of a request body, including the required JSON object:

Code Block
[
  "role1", "role2", "role3"
]

...