How-to guide
Approve command-line access
Let a script or tool use the Sovrain Admin API as you by entering the code it shows, and revoke it later.
This guide approves a request from a script or command-line tool that wants to use the Sovrain Admin API in your name. The tool shows a code; you enter it in Sovrain and choose what the tool may do.
Only admins can approve: members of the Owners or Admins group. Anyone else can only deny the request; see Roles.
Before you start
- Start the request yourself, from your own terminal. The tool shows a code such as
BCDF-GHJKand the address to open,https://acme.sovrain.net/device. The code works for 10 minutes. See Get an Admin API token for how a tool starts the request. - Sovrain needs a sign-in from the last 5 minutes. If yours is older, Sovrain asks you to sign in again.
Approve the request
- Open the address the tool shows. If the address already contains the code, it is filled in for you.
- On Connect a device, enter the Code and select Continue.
- On Command-line access is asking for access, check Requested from (the IP address), Program and When. If you did not start this from your own terminal, select Deny.
- The scopes the tool asked for are already ticked; untick any it does not need. If it asked for none, tick the ones it needs, or Select all. Scopes marked “can read and rotate app secrets” or “cannot be undone” give the tool the most power; leave them out unless the tool needs them.
- Select Approve.
Sovrain shows Access approved. Go back to your terminal: the tool now has its token.
The tool can do only what you ticked.
If something goes wrong
- This code has expired or was already used. Start the request again in your terminal to get a new code.
- Too many codes tried. Wait a few minutes, then try again. You typed 10 wrong codes within 5 minutes.
- Your account has no API access in this organization. Ask an administrator. You are not an admin, so you can only deny. Ask an admin to run the tool, or to make you an admin.
See and revoke what you approved
- Open the account menu, select Profile & settings, then API access (or select Manage API access on the page after approving).
- Each row shows the client, its scopes, when you approved it, when it was last used, when it ends and where it was requested from. Select Last 24 h to see the calls it made.
- Select Revoke to stop it. The tool stops at its next call.
Access also ends on its own, for example when the tool stops renewing it or when you change your password; see When a grant ends.
Related
- Review API access, to see every grant in the organization.
- Admin API reference