Access Roles API v2

Access Roles may be granted to users to offer access to password protected pages, preferential pricing (e.g. trade pricing).

The Access Roles API resource allows you to list built-in and manage custom Access Roles.

Scopes

Access to the Access Role API requires that the client have the following scopes granted:

  • roles - Permits write access to add, update or remove roles.
  • roles.readonly - Read only access to search or get role data.

The Access Role object

An Access Role represents a permission/grant, which may be required to access protected web pages, or offer users preferential Product Prices.

adminApprovalEmail
Optional email address. When a user registers for access an email will be sent to your default email address requesting approval. The recipient of approval requests may be changed to an alternative email address. Defaults to null to use system defaults. Only applicable when approvalMethod is set to admin.
adminApprovedUrl
Optional URL path starting with /. An email is sent to the user confirming approval of their account access. A link is provided within the email, which by default takes the user to their account dashboard, but may be changed to a custom URL. Defaults to null to use system defaults. Only applicable when approvalMethod is set to admin.
adminPendingUrl
Optional URL path starting with /. Users who are logged in to their account, but whose Access Role is pending approval may be redirected to a custom URL. Defaults to null to use system defaults. Only applicable when approvalMethod is set to admin.
adminRejectedUrl
Optional URL path starting with /. An email is sent to the user informing them that the application was not approved. The email may contain additional information and an additional URL may be provided. This may be to a policy document for approval, for example. The same URL is utilised if the user attempts to login. Defaults to null to use system defaults. Only applicable when approvalMethod is set to admin.
approvalMethod
May be one of the following values:
  • none (default)
    No approval method is required. When applying the Access Role to a user the role is instantly active.
  • email
    Requires that the user verify their email address. If the user has not already verified their email address, an email will be sent to the user containing a verification link.
  • admin
    Requires manual approval by an administrator before the Access Role is activated for a user.
createdOn read-only
The date and time the Geozone was created.
deniedUrl
Optional URL path starting with /. Users who are logged in to their account, but do not have access to pages protected by this access role may be redirected to a custom URL. Defaults to null to use system defaults.
emailValidationUrl
Optional URL path starting with /. Users who are logged in to their account, but have not verified their email address may be redirected to a custom URL. Defaults to null to use system defaults. Only applicable when approvalMethod is set to email.
id read-only
An unsigned 64-bit integer, which is unique across all Access Roles and all Evance Accounts.
isRequired read-only
A boolean indicating whether the Access Role is a protected/built-in role. Protected roles with a value of truecannot be modified. Currently, the only built-in Access Role is the customerrole. All custom Access Roles will have a value of false.
title
A title up to 50 characters long.
modifiedOn read-only
The date and time the Geozone was last modified.
reference
An alpha-numeric string containing lowercase characters a-z, numbers 0-9, underscores _, dashes -, and dots . up to 50 characters in length. The reference for an Access Role is unique for the account.
title
A title up to 50 characters long.

Example JSON

{
    "data": {
        "id": 53245,
        "reference": "trade-account",
        "title": "Trade Account",
        "deniedUrl": null,
        "approvalMethod": "admin",
        "emailValidationUrl": null,
        "adminPendingUrl": null,
        "adminApprovedUrl": null,
        "adminRejectedUrl": null,
        "adminApprovalEmail": "administrator@example.com",
        "createdOn": "2022-05-21T15:54:05+00:00",
        "modifiedOn": "2022-05-21T15:54:05+00:00"
    }
}

List/search Access Roles

GET /api/v2/roles.json

Get or search for one or more Access Roles.

Requires either the roles or roles.readonly OAuth scope.

Query parameters

id:in
Return Access Roles by a comma-separated list of IDs.
reference

Used to find a single Access Role by its reference property. The title must match the correct spelling (case-insensitive) - does not permit partial matches.

reference:in

A comma-separated list of references to find one or more Access Roles. The titles must match the correct spelling (case-insensitive) - does not permit partial matches.

title

Used to find a single Access Role by its title property. The title must match the correct spelling (case-insensitive) - does not permit partial matches.

title:in

A comma-separated list of titles to find one or more Access Roles. The titles must match the correct spelling (case-insensitive) - does not permit partial matches.


JSON response

Evance will return a JSON object containing the following properties:

success
A successful search request containing zero or more results will always return a true value.
status
An integer matching the HTTP response code. A successful request will have a status of 200.
data
An array containing zero or more Access Role data objects.
pagination
Search results include a pagination object contain information about the current page, total pages, the limit per page and the total number of results available.
  • limit - the number of results to return per page
  • page - the current page number
  • total - the total number of available results
  • totalPages - the total number of available pages of results
links
An object containing links to traverse available search results.
  • self - the URL for the current search.
  • previous - a URL for the previous results page, or null if there isn't one.
  • next - a URL for the next results page, or null if there isn't one


Example JSON response

In the example below you're able to see examples of Access Roles.

{
    "success": true,
    "status": 200,
    "data": [
        {
            "id": 53245,
            "reference": "trade-account",
            "title": "Trade Account",
            "deniedUrl": null,
            "approvalMethod": "admin",
            "emailValidationUrl": null,
            "adminPendingUrl": null,
            "adminApprovedUrl": null,
            "adminRejectedUrl": null,
            "adminApprovalEmail": "administrator@example.com",
            "createdOn": "2022-05-21T15:54:05+00:00",
            "modifiedOn": "2022-05-21T15:54:05+00:00"
        }
    ],
    "pagination": {
        "page": 1,
        "limit": 100,
        "total": 1,
        "totalPages": 1
    },
    "links": {
        "self": "https://examples.evance.me/api/v2/geozones.json",
        "previous": null,
        "next": null
    }
}

Get an Access Role

GET /api/v2/roles/{id}.json

Retrieve a single Access Role using its ID.

Requires either the roles or roles.readonly OAuth scope.

URL parameters

id required
The ID of the Access Role is supplied as a path parameter.


Response

Returns an object with the following properties:

success
A boolean where a value of true represents a successful request.
status
The HTTP status code e.g. 200 for a successful request.
data
Contains the Access Role object.


Example JSON response

{
    "success": true,
    "status": 200,
    "data": {
        "id": 53245,
        "reference": "trade-account",
        "title": "Trade Account",
        "deniedUrl": null,
        "approvalMethod": "admin",
        "emailValidationUrl": null,
        "adminPendingUrl": null,
        "adminApprovedUrl": null,
        "adminRejectedUrl": null,
        "adminApprovalEmail": "administrator@example.com",
        "createdOn": "2022-05-21T15:54:05+00:00",
        "modifiedOn": "2022-05-21T15:54:05+00:00"
    }
}


Add an Access Role

POST /api/v2/roles.json

Add an Access Role.

Requires the roles OAuth scope.

Request body

Your request body must contain an object including:

data required
Containing a Access Role object.


Example JSON request

The minimum requirement for an Access Role is a title value.

{
    "data": {
        "title": "Partner"
    }
}

In the example above, reference is omitted and will be auto-generated. However, we recommend defining the reference yourself.

{
    "data": {
        "title": "Partner",
        "reference": "partner"
    }
}

Success response

If the Access Role was created successfully you should receive a response with a 201 status code:

success
A boolean where a value of true means the object was created successfully.
status
The HTTP status code e.g. 201 means the object was created successfully.
data
Contains the Access Role object you created including its new id.


Error responses

If the Access Role could not be created you will encounter a response with a 422 status code:

success
A boolean where a value of false means the object could not be created.
status
A response code of 422 means the object could not be created and you should check the errors property for further information.
context
The context property indicates where the error occurred. For a 422 error this will typically contain a value of data, indicating that there was an error with the data object supplied.
errors

Contains an array of error objects, each will have the following properties:

  • name - The property name that encountered an error.
  • message - A human readable error message.
  • ref - An error reference string (e.g. error.not-unique if the alias supplied is already in use).


Update an Access Role

PUT /api/v2/roles/{id}.json

Update an existing Access Role by its ID.

Requires the roles OAuth scope.

URL parameters

id required
The ID of your Access Role object


Request body

Your request body must contain an object including:

data required
Containing updates to your Access Role object.


Example JSON request

To update an Access Role  you must PUT JSON to this resource within a data object. You do not need to supply all properties and may choose to only supply properties that require modifying. 

Note, changing the title of your Access Role, this will NOT auto-generate a new reference. 

{
    "data": {
        "title": "Trade Partner"
    }
}


Success response

If the Access Role was updated successfully you should receive a response with a 200 status code:

success
A boolean where a value of true means the object was saved successfully.
status
The HTTP status code e.g. 200 means the object was updated successfully.
data
Contains the Access Role object you updated.


Error responses

If the Access Role could not be updated you will encounter a response with either a 400, 403, 404 or 422status code:

success
A boolean where a value of false means the object could not be updated.
status
  • 400 may indicate that the ID was not provided.
  • 403 may be returned when an Access Role is protected and cannot be updated.
  • 404 means the Access Role could not be found by the IDs provided.
  • 422 means the Access Role could not be updated due to errors in the data.
context
  • parameters means the error is with the required id URL parameter.
  • data indicates an error within the Geozone object data.
errors

Contains an array of error objects, each will have the following properties:

  • name - The property name that encountered an error.
  • message - A human readable error message.
  • ref - An error reference string.


Delete an Access Role

DELETE /api/v2/roles/{id}.json

Delete an Access Role by its ID.

Requires the roles OAuth scope.

URL Parameters

id required
The ID of your Access Role object


Request body

Does not require a payload

Success response

If the Access Role was deleted successfully you should receive a response with a 204 status code and no body.

Error responses

If the Access Role could not be deleted you may encounter a response with a 400, 403, or 404 status code:

success
A boolean where a value of false means the object could not be deleted.
status
  • 400 may indicate that the ID was not provided, or the object could not be deleted for an unknown reason.
  • 403 indicatse that the Access Role is protected and may not be deleted.
  • 404 indicates that the ID was provided, but the object could not be found.