Connecting an app with OAuth
Back to the guide
Deeluge is an OAuth 2.1 authorization server. An application can ask a person for permission and then act as that person, bound by their role.
Use this when a person drives the application. For software running on its own, use an API key instead.
Discovery
Standard metadata endpoints, so a compliant client configures itself:
/.well-known/oauth-authorization-server
/.well-known/oauth-protected-resource
Clients can register dynamically rather than being set up by hand.
The flow
- Send the person to the authorization endpoint.
- They sign in if they are not already.
- The consent screen names your application, the account and firm it will act as, and the site they will be returned to, with a table of what you are asking for.
- They allow it, and you receive an authorization code.
- Exchange the code for an access token and a refresh token.
An authorization code is short-lived, valid for a few minutes. Access tokens last an hour; refresh tokens last 30 days.
Refresh token rotation
A refresh token is replaced every time it is used. Store the new one and discard the old.
Presenting a refresh token that has already been replaced revokes the entire grant. Every token it issued stops working, and the person must approve again.
That is the specification's replay detection, and it does what it should: a stolen refresh token becomes useless the moment either party uses it, because the second use is detected as a replay.
The practical consequence for you: never use a refresh token twice, never run two refreshes concurrently for the same grant, and persist the new token before making any further call. A race between two of your own processes looks exactly like theft and will be treated as such.
Permissions are live
The person's role is checked on every request, not at approval.
- Demoted, and the connection loses what their new role cannot do, on its next call
- Gone from the firm, and it stops working
Design for that. Access that worked yesterday can legitimately fail today without anybody revoking anything, so handle authorization failures as a normal condition rather than a bug.
Revocation
A person revokes a connection under Settings → Connected apps, which ends every token that grant issued. Your application can also revoke its own.
Expect revocation at any time and fail cleanly.
Scopes
The same scopes as API keys, with one difference: an OAuth connection is limited to what the approving person can do, so it can never exceed their role.
See Authentication and scopes.