Application Keys Plugin
Added in version 1.3.10.
The OctoPrint Application Keys Plugin comes bundled with OctoPrint.
It implements a workflow for third party apps or clients to obtain an application specific API key from OctoPrint to interact with it on a user’s behalf, via confirmation of the user through OctoPrint’s web interface. Existing keys can be managed on a per-user base as well as globally by administrators.
Workflow
The workflow to receive an API key for a third party client/an app via the Application Keys Plugin should consist of the following steps:
The User opens the App and gets prompted to enter or select an instance URL. Optionally (recommended!) the User also enters their username which is also their user ID into the App.
The App probes for workflow support on the Server. If this request doesn’t get an HTTP 204 No Content the App needs to direct the user to an alternative manual workflow (copy-paste API key) and abort this one. Otherwise it proceeds to the next step.
The App sends an Authorization request to the Server to start the authorization process.
The Server triggers a confirmation dialog for the User on the Webinterface (unused here) and returns an endpoint to the App to poll for a decision in the
Location
header of an HTTP 201 Created and an Authorization response (unused here).The App uses the obtained request specific endpoint to poll for a decision every second. An HTTP 202 Accepted signals that no decision has been made yet.
The User either accepts or denies the access request which makes the Webinterface send a decision request to the Server.
If the User accepted the request, the App receives an HTTP 200 OK with an attached API key response. If they deny it, the App will receive an HTTP 404 Not Found.
Workflow with redirect to auth dialog
Added in version 1.8.0.
Instead of asking the user to open the full blown OctoPrint interface to confirm the request, since OctoPrint 1.8.0 there also exists the alternative of redirecting the user to a basic auth dialog that allows logging in and confirming the request in a light-weight dialog. To implementat that, follow these steps:
The User opens the App and gets prompted to enter or select an instance URL. Optionally (recommended!) the User also enters their username which is also their user ID into the App.
The App probes for workflow support on the Server. If this request doesn’t get an HTTP 204 No Content the App needs to direct the user to an alternative manual workflow (copy-paste API key) and abort this one. Otherwise it proceeds to the next step.
The App sends an Authorization request to the Server to start the authorization process.
The Server triggers a confirmation dialog for the User on the Webinterface (unused here) and returns an endpoint to the App to poll for a decision in the
Location
header of an HTTP 201 Created and an Authorization response.The App opens a browser window with the provided auth_dialog URL for the user to log in and confirm the request. At the same time the App also uses the obtained request specific endpoint to poll for a decision every second. An HTTP 202 Accepted signals that no decision has been made yet.
The User logs in and either accepts or denies the access request which makes the auth dialog send a decision request to the Server.
If the User accepted the request, the App receives an HTTP 200 OK with an attached API key response. If they deny it, the App will receive an HTTP 404 Not Found.
API
Probe for workflow support
- GET /plugin/appkeys/probe
Probes for support of the workflow.
Normally returns an HTTP 204 No Content, indicating workflow availability. If a different status code is returned (usually an HTTP 404 Not Found), the plugin is disabled or not installed. Fall back to manual api key exchange.
- Status Codes:
204 No Content – the workflow is supported
Poll for decision on existing request
- GET /plugin/appkeys/request/<str:app_token>
Endpoint generated per authorization request to poll for the result.
Returns an HTTP 202 Accepted while no decision has been made yet, an HTTP 200 OK and a Key response if access has been granted and an HTTP 404 Not Found if the request has been denied or timed out.
Note
The request will be considered stale and deleted internally if the polling endpoint for it isn’t called for more than 5s.
- Status Codes:
200 OK – access granted, API key in response body
202 Accepted – no decision has been made yet, continue polling
404 Not Found – access denied or request timed out
Decide on existing request
- POST /plugin/appkeys/decision/<str:user_token>
Endpoint to decide on the authorization request.
Expects a Decision request as request body.
Returns an HTTP 204 No Content on success.
Requires the
PLUGIN_APPKEYS_GRANT
permissions and a recent credentials check.- JSON Parameters:
decision – boolean value to indicate whether to confirm (
True
) or deny (False
) access
- Status Codes:
204 No Content – success
Fetch list of existing application keys
- GET /api/plugin/appkeys
Fetches a list of existing application keys and pending requests registered in the system for the current user.
If the additional optional parameter
all
is provided and the user has thePLUGIN_APPKEYS_ADMIN
permission, fetches a list of all* application keys and pending requests registered in the system for any user.If the additional optional parameter
app
is provided, only the key for the specified application identifier and the current user will be returned. A user with thePLUGIN_APPKEYS_ADMIN``permission may also specify the ``user
parameter to fetch the key for the specified application identifier and a different user.Returns a 200 OK with a List response in the body upon success.
- Query Parameters:
all – Fetch all application keys and pending requests from all users. Requires the
PLUGIN_APPKEYS_ADMIN
permission.
Issue an application key command
- POST /api/plugin/appkeys
Application key commands allow revoking existing application keys and manually generating new ones. The available commands are:
- revoke
Revokes an existing application key. Must belong to the user issuing the command, unless the user has admin rights in which case they make revoke any application key in the system. Expects the key in question identified by the associated application identifier provided in the
app
parameter. Keys for other users but the current one can be revoked by admins with the additionaluser
parameter to specify the user id.- generate
Generates a new application key for the user, using the application identifier provided as parameter
app
. Keys for other users but the current one can be generated by admins with the additionaluser
parameter to specify the user id.
Upon success, a status code of 204 No Content and an empty body is returned.
Requires user rights and a fresh credentials check.
Deprecated since version 1.10.0: Revoking a key by supplying the key itself has been deprecated as of OctoPrint 1.10.0. Use
app
and optionallyuser
instead.Example revoke request
Revokes the key associated with app id
test
for the current user.POST /api/plugin/appkeys HTTP/1.1 Host: example.com Content-Type: application/json X-Api-Key: abcdef... { "command": "revoke", "app": "test" }
HTTP/1.1 204 No Content
Example revoke request by an admin for a different user
Revokes the key associated with the app id
test
for useruser
.POST /api/plugin/appkeys HTTP/1.1 Host: example.com Content-Type: application/json X-Api-Key: abcdef... { "command": "revoke", "app": "test", "user": "user" }
HTTP/1.1 204 No Content
Example generate request
Generates a new key for application identifier “My awesome application 1.0”.
POST /api/plugin/appkeys HTTP/1.1 Host: example.com Content-Type: application/json X-Api-Key: abcdef... { "command": "generate", "app": "My awesome application 1.0" }
HTTP/1.1 200 OK Content-Type: application/json { "app_id": "My awesome application 1.0", "user_id": "me", "api_key": "abcdef1234567890" }
- JSON Parameters:
command (string) – The command to issue, either
revoke
orgenerate
app (string) –
revoke
&generate
commands: The application identifier of the key to revoke or generate.user (string) –
revoke
&generate
commands: The user name for which to revoke or generated a key associated with the provided app id. If not provided, the current user’s name will be used.key (string) –
revoke
command: The key to revoke. Revoking by providing the key itself has been deprecated as of OctoPrint 1.10.0. Useapp
and optionallyuser
instead.
- Status Codes:
200 OK – Key generation successful
204 No Content – No error during key revocation
400 Bad Request – Invalid or missing parameter
Data model
Key response
Name |
Multiplicity |
Type |
Description |
---|---|---|---|
|
1 |
str |
the API key generated for the application |
Decision request
Name |
Multiplicity |
Type |
Description |
---|---|---|---|
|
1 |
boolean |
|
List response
Name |
Multiplicity |
Type |
Description |
---|---|---|---|
|
1 |
list of key list entries |
Keys registered in the system |
|
1 |
list of pending list entries |
Currently pending authorization requests |
Key list entry
Name |
Multiplicity |
Type |
Description |
---|---|---|---|
|
1 |
str |
API key |
|
1 |
str |
Application identifier |
|
1 |
str |
User ID of the key’s owner |
Pending list entry
Name |
Multiplicity |
Type |
Description |
---|---|---|---|
|
1 |
str |
Application identifier |
|
0..1 |
str |
optional: User ID of user who can grant or deny request |
|
1 |
str |
Token to grant or deny request |
JavaScript Client Library
- OctoPrintClient.plugins.appkeys.getKey(app, user, opts)
Retrieves the key information the given
app
and optional otheruser
. The key must belong to the current user, or the current user must have thePLUGIN_APPKEYS_ADMIN
permission.See Fetch list of existing application keys for more details.
- Arguments:
app (
string()
) – Application identifieruser (
string()
) – Optional user identifieropts (
object()
) – Additional options for the request
- Returns Promise:
A jQuery Promise for the request’s response
- OctoPrintClient.plugins.appkeys.getKeys(opts)
Retrieves registered keys and pending requests for the current user.
See Fetch list of existing application keys for more details.
- Arguments:
opts (
object()
) – Additional options for the request
- Returns Promise:
A jQuery Promise for the request’s response
- OctoPrintClient.plugins.appkeys.getAllKeys(opts)
Retrieves registered keys and pending requests for all users.
Needs the
PLUGIN_APPKEYS_ADMIN
permission.See Fetch list of existing application keys for more details.
- Arguments:
opts (
object()
) – Additional options for the request
- Returns Promise:
A jQuery Promise for the request’s response
- OctoPrintClient.plugins.appkeys.generateKey(app, opts)
Generates a key for the given
app
and the current user.See Issue an application key command for details.
- Arguments:
app (
string()
) – Application identifieropts (
object()
) – Additional options for the request
- Returns Promise:
A jQuery Promise for the request’s response
- OctoPrintClient.plugins.appkeys.revokeKey(key, opts)
Revokes the given
key
. The key must belong to the current user, or the current user must have thePLUGIN_APPKEYS_ADMIN
permission.See Issue an application key command for details.
Deprecated since version 1.10.0:
revokeKey
has been deprecated. UserevokeKeyForApp
instead.- Arguments:
key (
string()
) – Key to revokeopts (
object()
) – Additional options for the request
- Returns Promise:
A jQuery Promise for the request’s response
- OctoPrintClient.plugins.appkeys.revokeKeyForApp(app, user, opts)
Revokes the key for the given
app
and optional otheruser
. The key must belong to the current user, or the current user must have thePLUGIN_APPKEYS_ADMIN
permission.See Issue an application key command for details.
- Arguments:
app (
string()
) – Application identifieruser (
string()
) – Optional user identifieropts (
object()
) – Additional options for the request
- Returns Promise:
A jQuery Promise for the request’s response
- OctoPrintClient.plugins.appkeys.decide(token, decision, opts)
Decides on an existing authorization request.
See Decide on existing request for more details.
- Arguments:
token (
string()
) – User token for which to make the decision, as pushed to the client via the socket.decision (
boolean()
) – Whether to grant access (true
) or not (false
).opts (
object()
) – Additional options for the request
- Returns Promise:
A jQuery Promise for the request’s response
- OctoPrintClient.plugins.appkeys.probe(opts)
Probes for workflow support.
See Probe for workflow support for more details.
- Arguments:
opts (
object()
) – Additional options for the request
- Returns Promise:
A jQuery Promise for the request’s response
- OctoPrintClient.plugins.appkeys.request(app, opts)
Starts a new authorization request for the provided
app
identifier.See Start authorization process for more details.
- Arguments:
opts (
object()
) – Additional options for the request
- Returns Promise:
A jQuery Promise for the request’s response
- OctoPrintClient.plugins.appkeys.requestForUser(app, user, opts)
Starts a new authorization request for the provided
app
anduser
identifiers.See Start authorization process for more details.
- Arguments:
opts (
object()
) – Additional options for the request
- Returns Promise:
A jQuery Promise for the request’s response
- OctoPrintClient.plugins.appkeys.checkDecision(token, opts)
Polls for a decision on an existing authorization request identified by
token
.See Poll for decision on existing request for more details.
- Arguments:
opts (
object()
) – Additional options for the request
- Returns Promise:
A jQuery Promise for the request’s response
- OctoPrintClient.plugins.appkeys.authenticate(app, user, opts)
Convenience function that probes for support, issues a request and then automatically starts polling for a decision on the returned polling endpoint every 1s, until either a positive or negative decision is returned. On success the returned promise is resolved with the generated API key as argument. If anything goes wrong or there is no support for the workflow, the promise is rejected.
Example usage
OctoPrint.plugins.appkeys.authenticate("My App", "some_user") .done(function(api_key) { console.log("Got our API key:", api_key); }) .fail(function() { console.log("No API key for us"); })
- Arguments:
app (
string()
) – Application identifieruser (
string()
) – Optional user identifieropts (
object()
) – Additional options for the request
- Returns Promise:
A jQuery Promise for the request’s response
Source code
The source of the Application Keys plugin is bundled with OctoPrint and can be found in
its source repository under src/octoprint/plugins/appkeys
.