API Tokens

To access Simscope from the command-line and via REST API's, Simscope requires using API tokens for User Authentication (instead of plain user/password authentication).

• An API Token maps a hexadecimal string → authenticated user.

Example API token:

• 59ace5f310814cc

Restrictions

Currently, each user can have up to one API token. If you request a new API token, the previous one is automatically revoked and replaced.

Requesting a Simscope API Token (as a user)

Any user can request a Simscope API token from the command-line by running:

> bin/simscope apitoken SIMSCOPE_URL

# Example (with hostname)
> bin/simscope apitoken http://simscope-servername:8080

# Example (with IP)
> bin/simscope apitoken http://123.45.67.89:8080

Example apitoken session:

> bin/simscope apitoken http://server.company.com:8091

UserID: pdq
Password: xxxxxxxxxx

Simscope API token successfully stored to /home/pdq/.simscope.apitoken

This automatically saved the API token to the user's home directory:
→ /home/pdq/.simscope.apitoken

Admin: Requesting an API Token via the Web Interface

Administrators can request a user API token from the Simscope web site:

1. Navigate to Admin → User Accounts
2. Click on the Edit link on the right side of the desired User.
3. Click [Issue new API Token].

You will see a message similar to:

API token issued for user Charles: 59ace5f310814cc
Save this into your command-line scripts.

The user will also receive an API token email message.

You will also see a message similar to this on the terminal:

2020-03-18 22:47:57 [INFO ] Issued API token user=Charles

Here is a screenshot of creating an API token:

Manually creating ~/.simscope.apitoken

NOTE: this section can be ignored if using the simscope apitoken tool.

When running command-line Simscope scripts, the file ~/.simscope.apitoken is automatically read to find a user's API token locally.

You can create a special file in your home directory called ~/.simscope.apitoken, with the API token stored in it.

• This file needs to have private user permissions: -rw------- (ie 0600). You can set this via:

> chmod 600 ~/.simscope.apitoken

Special token: Admin API token from the web

Simscope automatically stores a file on disk at $SIMSCOPE_DB/simscope-admin.apitoken with the admin user's API token.

This allows scripts to read the file and access Simscope's API without needing to create separate API tokens.

Notes:

• The file is stored on disk with private user permissions 0600
• For security, the API token automatically rotates every time the Simscope server restarts.

Example admin API token usage from curl:

> curl --location --data-urlencode "apitoken@$HOME/.simscope.apitoken" -G \
"http://server:8080/api/config/whoami"

• Note: this token should not be shared with any non-admin users.

Using API Tokens from scripts

Alternatively, many of the Simscope scripts take a CLI option called --apitoken to set within another shell script.

Basic CURL command with an API token

→ See curl for examples using API tokens.

Example REST API Token error

If you receive this error similar to this when running a script accessing Simscope:

REST not authenticated: invalid apitoken: contact VerOps for API token help"

This indicates you either have not provided an API token or your API token is not valid.

• To remedy, either fix the token or you can replace your API token by following the directions above.