Creating and managing API tokens

Many users of the POD Aggregator, regardless of whether they are data providers or data consumers, will want to interact with its API. To do so, you will need to create an access token, which is provided by the Aggregator at the level of individual organizations (data providers). You will need to have Organization owner privileges (or POD administrator privileges) to do this for your organization. (If you are an organization owner, you may also want to consult our Organization owner's manual.)

Note: Tokens are like passwords and should be treated as such - don't place them in public documents, or in public source code repositories.

Creating tokens

1. Log into the POD Aggregator with your personal username and password.
2. Navigate to your organization's dashboard page. (From the Aggregator front page, look for the "My Organizations" heading, and then click on the link labeled with your organization's name.). Once on your organization's dashboard page, look for the "Organization management" section. (It will be towards the bottom of the page.)
3. In this section, there will be an "Access Tokens" panel. Click the "Manage tokens" button within it.
4. You will see a listing of access tokens your organization already has. (Initially, your organization might not have any tokens.) If you need to create a new access token, click the "Create token" button.
5. In the resulting "New token" page, type in an optional label for the token (e.g. batch upload) and select the scope for the token before you click "Create token." :
   • all: The token can be used for uploads and downloads
   • upload-only: The token can be used only for uploads; it will not work for downloads
   • download-only: The token can be used only for downloads; it will not work for uploads. Recommended if you are regularly fetching batches of records.
6. After you click on "Create token" on this page, you will be returned to your organization's "Manage tokens" page, and you should see the new token on a line by itself. Copy the token and save it somewhere safe to use in your scripts or batch processes.

Managing and revoking tokens

You may want to revoke (delete or retire) a token if it's no longer used, or if it has been compromised.

1. Log into the POD Aggregator with your personal username and password.
2. Navigate to your organization's dashboard page and look for the "Organization management" section.
3. In this section, there will be an "Access Tokens" panel. Click the "Manage tokens" button within it.
4. On line for the appropriate token, click the "Revoke" button. You will be asked to confirm that you want to revoke that token.
5. You should see a message that says "Token was successfully destroyed." That token will no longer work for authentication.