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.

In 12.9 and later, every REST API call that uses POST, PATCH, PUT, or DELETE requires cross-site request forgery (CSRF) protection. When you request a token, the response sets a BravuraSecurityFabric-CSRF-Token cookie. Each of these calls must send the bearer token, that cookie, and an X-CSRF-Token header whose value is the URL-decoded cookie value. GET, HEAD, and OPTIONS calls do not need the header. A call that fails the check returns HTTP 403 with the message CSRF token validation failed.

Swagger UI does not send the X-CSRF-Token header, so a PATCH call from Swagger UI returns HTTP 403. In 12.9 and later, this guide uses Swagger UI to log in and to run the GET calls, and uses curl for the two PATCH calls.

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}).

In 12.9 and later, this call requires an X-CSRF-Token header, and Swagger UI does not send it. You send the request with curl instead.

  1. Request a token, and save the cookies that the response sets. Replace the placeholders with your values.

    curl --cookie-jar cookies.txt --data-urlencode "grant_type=password" --data-urlencode "client_id=passwordclient" --data-urlencode "username=User1" --data-urlencode "password=<password-of-User1>" "https://<server-fqdn>/<instancename>/identity/connect/token"

    Copy the access_token value from the response. This token is separate from the one that Swagger UI holds.

    Note

    On Windows, run curl.exe from Command Prompt. In PowerShell, curl is an alias for a different command and does not accept these options.

  2. Open cookies.txt in a text editor. Copy the value at the end of the line for the BravuraSecurityFabric-CSRF-Token cookie, and then decode it. Replace %2F with /, %2B with +, and %3D with =.

  3. Save the following json as password.json. The PATCH /accounts({accountKey}) endpoint supports replace, remove, and test operations. This example uses the replace operation to change the account’s password to Qwerty123.

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

  4. Send the request. Replace <access-token>, <decoded-csrf-token>, and <accountKey> with your values. The --include option shows the response headers.

    curl --include --request PATCH --cookie cookies.txt --header "Authorization: Bearer <access-token>" --header "X-CSRF-Token: <decoded-csrf-token>" --header "Content-Type: application/json" --data "@password.json" "https://<server-fqdn>/<instancename>/api/rest/v2/accounts(<accountKey>)"

  5. Check that the response starts with HTTP/1.1 202 Accepted. The request was submitted, but this does not tell you the status of the password change.

    The location response header contains the operation key of the request. Use it 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.

In 12.9 and later, you send the PATCH request with curl, as described in Changing an account password.

  1. Save the following json as password.json, replacing the earlier file. This example uses the test operation to verify that the account’s password is Qwerty123.

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

  2. Send the request. Use the access token and the decoded CSRF token that you got in Changing an account password. If an hour has passed, the access token has expired, so repeat the token request and the cookie decoding first.

    curl --include --request PATCH --cookie cookies.txt --header "Authorization: Bearer <access-token>" --header "X-CSRF-Token: <decoded-csrf-token>" --header "Content-Type: application/json" --data "@password.json" "https://<server-fqdn>/<instancename>/api/rest/v2/accounts(<accountKey>)"

  3. Check that the response starts with HTTP/1.1 202 Accepted. The request was accepted, but you must check whether the test operation completed.

    Copy the operation ID from the location response header.

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

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

  6. Click Try it out.

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

  8. Click Execute.

    42737.png

  9. 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: