meta.sr.ht OAuth Reference

Authentication with all sr.ht services is done with OAuth and is governed by meta.sr.ht.

Supported authentication profiles

There are various ways, in order of complexity and flexibility, of authenticating with the APIs around sr.ht. Your goal is to obtain an access token, which can be used to authenticate with sr.ht APIs.

Personal Access Tokens

The easiest and fastest way to authenticate with sr.ht is to create a personal access token. This token will have unrestricted access to all sr.ht APIs and can be used like a normal access token to authenticate API requests (see Authenticating API requests).

Warning: do not give your personal access tokens to third parties. Any third party which encourages you to give them a personal access token should instead develop an OAuth client as described in the next section.

OAuth Clients

Personal access tokens are suitable for authenticating yourself, but if you intend to provide software that other sr.ht users can log into, you should create an OAuth client instead. The OAuth flow allows end-users to grant your client only the privileges it requires to execute its duties and to revoke this access at any time. This is accomplished through an OAuth exchange:

Direct the user (in a web browser) to a special page on meta.sr.ht where we present them with the permissions you're asking for and they provide consent.
The user is redirected back to your application's base redirect URI. We will add an exchange token to the query string.
Your application sends an HTTP request directly to meta.sr.ht using this exchange token and your client credentials to obtain an access token.

To this end, you need to have an HTTP server running somewhere (localhost is suitable for testing) that the user can be redirected to upon consenting to the permissions you requested. Decide on a URL we can redirect the user to in your application, and fill out the base redirect URI accordingly.

Upon submitting the form, your client ID and client secret will be shown to you. Record your client secret now. It will not be shown to you again.

To start the exchange, direct the user to the following URL:

https://meta.sr.ht/oauth/authorize

Provide the following parameters in the query string:

client_id: The client ID assigned to you in the previous step.
scopes: A list of scopes you're requesting — see next section.
state: Optional: an arbitrary string — see notes.
redirect_uri: Optional: your application URI for redirect the user to — see notes.

The optional state field is returned to you after the redirect. One example use-case of this field is generating a token before directing the user to the authorization page and validating it after the redirect, to prevent users from initiating the OAuth flow without you. Most users don't need to worry about this.

The optional redirect_uri field can allow you to specify a route more precise than the base URI affords, for example to include a user ID. The redirect_uri must begin with the base_uri.

OAuth scopes

API endpoints on sr.ht generally require an access token valid for a specific scope to be used. This allows you to only request access to the subset of the API that you require. Scopes are written with the following notation(s):

name
name:access
service/name:access

name is the name of the OAuth scope, which is documented alongside the API endpoints which require it (e.g. /api/user/profile requires the profile scope). access is either read or write, and may be omitted (default: read). service is the name of the service for which the scope is applicable. If omitted, the default is meta.sr.ht. The following services are also recognized:

git.sr.ht
builds.sr.ht
todo.sr.ht
lists.sr.ht
man.sr.ht

The application redirect

Once the user consents, they will be redirected to your redirect_uri, or the base_uri for your client if unspecified. We will update your redirect URI with some additional query string parameters you can use for the next steps:

exchange: An exchange token you can use to obtain an access token in the next step.
scopes: The list of OAuth scopes the user consented to.
error: If present, indicates that an error occurred in the process — see notes.
details: If present, a human friendly error string, if that human is an engineer.

Possible values for error:

invalid_redirect
invalid_scope
user_declined

Important: the user is able to edit the scopes you've requested before consenting. You must handle the case where the scopes returned in the redirect do not match the scopes you requested.

Obtaining an access token

Once your application retrieves the exchange token from the redirect, you can submit an HTTP POST request to https://meta.sr.ht/oauth/exchange. The request body should be application/json and include the following parameters:

client_id: The client ID assigned to you when you registered the application.
client_secret: The client secret assigned to you when you registered the application.
exchange: The exchange token issued in the previous step.

You will receive a response like this:

{
    "token": "your access token",
    "expires": "%Y-%m-%dT%H:%M:%S"
}

You can now use this token for Authenticating API requests.

Authenticating API requests

Authenticating your API request is simple once you have an access token. You just need to set the Authorization header to token your-access-token. For example:

curl \
    -H Authorization:'token <your-access-token>' \
    https://meta.sr.ht/api/user/profile

OAuth Maintenance

meta.sr.ht offers several resources for ongoing maintenance of an OAuth client and its access tokens.

Refreshing access tokens

TODO

Rotating your client secret

On the security tab of your OAuth client's dashboard (which can be accessed from the OAuth summary on your account), you can rotate your client secret, in the event that it is compromised.

Revoking access tokens

On the security tab of your OAuth client's dashboard (which can be accessed from the OAuth summary on your account), you can revoke all issued access tokens at once, in the event some or all of them are compromised. Users will have to repeat the authorization flow.