Skip to main content
  • Bravura Security Fabric Documentation
  • API
  • REST API quick start

REST API quick start

This guide provides a simple example using the REST API. This is done using Swagger UI , which is included with Bravura Security Fabric .

Swagger UI is an interactive API documentation that allows users to execute REST API endpoints directly in the browser. By using Swagger UI, it will be easy to visualize what is being passed into the REST API and what is being returned. In addition, Swagger UI does not require any additional installation.

This example involves a user changing their own account password and verifying that it has been changed. The workflow is as follows:

  1. A user logs into the REST API and gets an authentication (bearer) token

  2. The user calls an endpoint to get a list of their associated accounts

  3. The user calls an endpoint to get an account based on a key

  4. The user calls an endpoint to change the account’s password

  5. The user calls an endpoint to get the result of the password change

  6. The user calls an endpoint to test the account’s password

  7. The user calls an endpoint to get the result of the password test

  8. The user logs out of the REST API

By default, users can list their own accounts, and change and verify their own passwords, however users cannot view or act on other users’ accounts. This is enforced using Open Policy Agent authorization policy rules. Thus, some endpoints cannot be run unless additional permissions are granted. See our REST API Reference for more information.

Preparation

The user must be provisioned to use the REST API. To do this, add the user to the _EXPLICIT_REST_API_USERS_ user class. An example user User1 will be used throughout this QuickStart guide.

  1. Log into the Bravura Security Fabric instance as a superuser.

  2. Go to Manage the system > Policies > User classes.

  3. Locate and click on _EXPLICIT_REST_API_USERS_.

  4. Click Explicit Users.

  5. Click Select…

  6. Locate and select the user that will be used to access the REST API (User1).

  7. Click Add.

Login

To access the endpoints, the user needs to log in to the REST API. Upon successful authentication, a bearer token will be issued which will grant the user access to the REST API for 3600 seconds (1 hour).

  1. From a web browser, go to:

    https://<ip-of-fabric-instance>/<instancename>/api/rest/swagger/index.html

    If the instance is not using SSL, go to:

    http://<ip-of-fabric-instance>/<instancename>/api/rest/swagger/index.html

  2. Click Authorize.

    REST_login_authorize

  3. Enter the following:

    1. username: User1

    2. password: <password-of-User1>

    3. client_id: passwordclient

    4. Scopes: select all

    REST_login_authorizations

  4. Click Authorize.

    It may take a few moments to return the authorization result.

  5. Check that the session is authorized (a bearer token is issued at this stage).

    REST_login_token

    The bearer token value will not be explicitly shown upon log in using Swagger UI.

    Note that authenticating to the REST API uses a Token URL, which is different than a Request URL, which is used for calling endpoints.

  6. Exit out of the dialog box, by either clicking Close or x on the top right of the dialog box.

Get a list of accounts

Now that the user is logged into the REST API, they can obtain a list of their associated accounts. The endpoint used to achieve this is GET /accounts.

  1. From Swagger UI, locate GET /accounts, which is under Accounts.

    42719.png

  2. Click GET /accounts.

  3. View the parameters available for the endpoint, which is mainly used to format or filter the results returned. These are optional fields but can be useful to specify, especially if there are a lot of results returned. Not all endpoints will have the same parameters, and some may have required fields, so be sure to go through each endpoint to see what is applicable.

    42720.png

    You can also see what response codes will be returned from this endpoint, as well as an example response body in json format.

    42721.png

  4. Click Try it out to get the list of accounts for User1.

    42722.png

    We can leave the parameters blank for now.

  5. Scroll down and click Execute.

    42723.png

  6. Check that the endpoint returned a 200 (Success) code, and displayed the response body with the list of User1’s accounts.

    42724.png

    You should also see the Curl and Request URL used for the endpoint execution. This can be useful to note if you want to know what headers and other inputs are required if you want to execute this in an external program. It is where you can also see the bearer token issued for this session.

  7. Choose the account to change the password for. The account’s id is needed, so for this example, we will choose the first one with id: 1a7145c0-537c-4e77-af36-1a7e6ead288a.

Get an account by key

This step is not required, but it can be helpful to see which endpoint can be used if you already know the account’s ID, which we do from the previous step. The endpoint used to achieve this is GET /accounts({accountKey}) .

  1. From Swagger UI, locate GET /accounts({accountKey}), which is under Accounts.

    42725.png

  2. Click GET /accounts({accountKey}).

  3. Click Try it out.

    42726.png

  4. Since we already know the ID of the account, fill it in the accountKey field.

    42727.png

  5. Click Execute.

  6. Check that it returns a 200 (Success) code and displays the response body with the chosen account of User1.

    42728.png

    It is good practice to observe the Curl and Request URL to see exactly what is being passed in.

Changing an account password

Now that we know the ID of the account, we can now change its password. The endpoint used to achieve this is PATCH /accounts({accountKey}).

  1. From Swagger UI, locate PATCH /accounts({accountKey}), which is under Accounts.

    42729.png

  2. Click PATCH /accounts({accountKey}) .

  3. Click Try it out.

  4. Fill in the accountKey field, and provide json containing the operation and password in the request body.

    PATCH /accounts({accountKey}) supports replace, remove and test operations.

    • replace: change a password

    • remove: remove a password

    • test: verify a password

    An example json looks like:

    [
   {
      "op":"replace",
      "path":"/password",
      "value":"Qwerty123"
   }
]

    Here, we will change the account’s password to Qwerty123 using the replace operation.

  5. Click Execute.

    42730.png

  6. Check that the endpoint returned a 202 (Accepted) code; the request was successfully submitted, however it does not tell us the status of the password change.

    42731.png

    The response header returns a location field, containing the operation key of the request (in this case, 90cd48c8-e1de-4801-981e-a7699c2a4ec6) We will use that to get the operation result.

Get the operation result

We can get the operation result of the password change since we know the operation ID. The endpoint used to achieve this is GET /operations({key}) .

  1. From Swagger UI, locate GET /operations({key}), which is under Operations.

    42732.png

  2. Click GET /operations({key}) .

  3. Click Try it out.

  4. Fill in the key field with the operation ID of the password change.

  5. Click Execute.

    42733.png

  6. Check that it returned a 200 (Success) code as well as display the response body containing the status of the password change (in this case, it also succeeded).

    42734.png

    Typically, the details of the operation should be returned instantly, however it could take a few moments to appear. If it does not appear, this means that the operation is still not complete. In this case, you may need to run the endpoint several times until you get a result.

    Status codes:

    • S = Success

    • F = Failure

    • R = Still running

Test the password

The steps to test a password is identical to changing a password, except with a different operation type. It will also require running an endpoint to get the operation result.

  1. From Swagger UI, locate PATCH /accounts({accountKey}), which is under Accounts.

  2. Click PATCH /accounts({accountKey}).

  3. Click Try it out.

  4. Fill in the accountKey field and provide json code containing the operation and password in the request body.

    An example json looks like:

    [
   {
      "op":"test",
      "path":"/password",
      "value":"Qwerty123"
   }
]

    Here, we will verify that the account’s password is set to Qwerty123 using the test operation.

  5. Click Execute.

    42735.png

    The request was accepted but now we must see whether the test operation completed

  6. Obtain the operation ID from the location field in the response header (in this case, 8d293fb2-8b03-4b30-8ea9-a774a8c34dff)

    42736.png

  7. From Swagger UI, locate GET /operations({key}), which is under Operations.

  8. Click GET /operations({key}).

  9. Click Try it out.

  10. Fill in the key field with the operation ID of the password test.

  11. Click Execute.

    42737.png

  12. Check that it returned a 200 (Success) code as well as display the response body containing the status of the password test (in this case, it also succeeded)

    42738.png

    The details of the operation should be returned instantly; otherwise you may need to run the endpoint several times until you get a result.

Exercise

Since the account password of User1 has been changed to Qwerty123, try to change it back to the original password and verify that it has been successfully changed, all using endpoints from the REST API.

Logout

After changing and testing the password, we can log out of the REST API. This will revoke the authentication token and prevent further calls to the REST API unless the user logs in again.

  1. Click Authorize.

    REST_login_authorize

  2. Click Logout.

    42739.png

Next steps

By now, you should be familiar with how to log into the REST API and run endpoints. You can also try running REST API endpoints on Postman, by importing the schema referenced in the Swagger UI, ie:

http://<ip-of-fabric-instance>/<instancename>/api/rest/swagger/v1/swagger.json

Refer to the REST API Reference documentation for more information on supported endpoints.

In this section: