Authentication

Authentication is a crucial aspect of using the Silverbucket Customer API, ensuring secure access to your organization's data. This guide will walk you through the steps to set up and manage authentication tokens for API access.


Setting Up an API User

Authorization tokens are tied to specific users in Silverbucket. To ensure a secure and manageable API access process, we recommend creating a dedicated API user with the following details:
  • Username: api.user
  • First name: user
  • Last name: API
  • Full access rights: true
  • Admin rights: true

Store User ID

For testing purposes, record the internal ID of the API user. You can find this ID in the URL of the API user's Dashboard:
URL: https://<your_environment>.agbucket.com/m/people/<user_id>
When the API user is later on in these instructions hidden, there is no easy way to access the User's Dashboard and retrieve this information.


Token Management

Only administrators have the privilege to manage authorization tokens. To access Token Management:
  • Click on the ellipsis icon in the top navigation bar.
  • From the context menu, select "Admin."
  • In the Admin view, navigate to the "System settings" tab.
  • Select "Token management."

Creating a Token

    .1Click the "Create token" button.
    .2Choose the API user created in the previous step.
    .3Click "Create."
    .4Copy the generated token from the dialog (it won't be listed elsewhere).
The new token is now generated and associated with the designated API user.


Hiding API User

To prevent the API user from appearing in general Silverbucket views:
  • Go to the Administrator view's "Users" tab.
  • Search for "api.user" in the Free text search field.
  • Click the "Update report" button.
  • Select the Edit link for the API user from the result list.
  • Scroll down in the Edit user dialog and set "Stealth" to true.
  • Click "Save."
This action hides the API user from most Silverbucket views, reducing confusion for regular users.


Testing the Token

With the token and the API user's ID, you can test the authentication. Make an API call to the users endpoint:
curl --request GET \
  --url https://<your_environment>.agbucket.com/customer-api/1.0/users/?user.id=<user_id> \
  --header 'Authorization: Token xyz123' \
  --header 'Content-Type: application/json'


Example Response

{
    "count": 1,
    "csvUrl": "/customer-api/1.0/users/?user.id=<user_id>&csv=true",
    "itemsPerPage": 500,
    "excelUrl": "/customer-api/1.0/users/?user.id=<user_id>&excel=true",
    "next": null,
    "current": 1,
    "lastPage": 1,
    "data": [
        {
            "id": <user_id>,
            "last_login": null,
            "username": "api.user",
            "first_name": "user",
            "last_name": "API",
            "email": "",
            "is_superuser": true,
            "is_staff": true,
            "is_contractuser": false,
            "is_mainuser": false,
            "is_active": true,
            "date_joined": "2019-08-14T12:44:51.386273",
            "startdate": "2019-08-14",
            "enddate": null,
            "dayload": "8.00",
            "language": "en",
            "is_external": false,
            "is_stealth": true,
            "cost_price": null,
            "hourly_rate": null,
            "external_id": null,
            "capacity": "100.00",
            "is_future_talent": false,
            "node": null,
            "country": null,
            "site": null,
            "cost_center": null,
            "default_role": 1,
            "supervisor": null,
            "calendar": null,
            "currency": 1
        }
    ],
    "previous": null
}



Security Considerations

  • Keep authentication tokens confidential.
  • Do not hardcode tokens in your source code.
  • Implement token rotation, expiration, and revocation policies.