Documentation » API » Authentication

Smithereen users the industry standard OAuth 2.0 protocol for user authentication.

Native and web client applications – implicit flow

Receive an access token directly in your app.

Important: do not use this flow to authenticate users in your service! Use the authorization code flow instead.

In a web view or user’s browser, open https://<server address>/oauth/authorize with the following query parameters added:

  • client_id – your application ID. Required.
  • response_type – must be set to token.
  • redirect_uri – the URL where you will receive your access token. Can either be something with a custom scheme, for native apps using a browser, or an https URL you control for web apps or native apps using a web view. Must be specified in the app’s metadata. Required.
  • scope – space-separated list of permissions you’re requesting. Optional.
  • state – an opaque string that will passed back to your app. Optional.

Example URL:

https://smithereen.local/oauth/authorize?client_id=https%3A%2F%2Fsmithereen.local%2Fapps%2F1&response_type=token&redirect_uri=my-cool-app%3A%2F%2Foauth-callback&scope=friends+photos+offline

Upon successful authentication, the user will be redirected to the redirect_uri you specified, with the following parameters added as the fragment:

  • access_token – the token itself
  • token_type – bearer as required by OAuth spec
  • expires_in – if you didn’t request the offline scope, token lifetime in seconds
  • state – the state string you previously passed to the authorization endpoint, if any
  • user_id – the identifier of the user for which this token was issued

Example:

my-cool-app://oauth-callback#access_token=b8ij6EICnZ8wMpWG0czn4yilNPh-F52IsBm9a5K3yYHq_6L_NGX8JfZv-xsAEA5O8_BLuEkaZJemtsbKbJ2cBg&token_type=bearer&user_id=123

Server applications – authorization code flow

Receive an authorization code to then exchange to an access token. Use this to let users log into your service using their Smithereen accounts and for other cases where you need to call Smithereen API from your server, for example, a bridge or a post scheduling service. You can also use this flow for client apps, when you aren’t sure of the security of whichever mechanism you’re using to intercept the redirect to redirect_uri.

In a web view or user’s browser, open https://&lt;server address>/oauth/authorize with the following query parameters added:

  • client_id – your application ID. Required.
  • response_type – must be set to code.
  • redirect_uri – the URL where you will receive your authorization code. Must be specified in the app’s metadata. Required.
  • scope – space-separated list of permissions you’re requesting. Optional.
  • state – an opaque string that will passed back to your app. Optional.
  • code_challenge_method – if using PKCE (recommended), set this to S256. Optional.
  • code_challenge – if using PKCE, the base64-encoded SHA-256 hash of the code verifier string. Optional.

Example URL:

https://smithereen.local/oauth/authorize?client_id=https%3A%2F%2Fsmithereen.local%2Fapps%2F1&response_type=code&redirect_uri=https%3A%2F%2Fexample.com%2Fsmithereen_callback&scope=friends+photos+offline

Upon successful authentication, the user will be redirected to the redirect_uri you specified, with the following query parameters added:

  • code – the authorization code
  • state – the state string you previously passed to the authorization endpoint, if any

Then you would send the code to your server and exchange it for an access token by making a POST request to https://&lt;server address>/oauth/token with the following parameters sent as form data:

  • grant_type must be set to authorization_code
  • code – the code you received
  • redirect_uri – the redirect URI you used
  • client_id – your application ID
  • code_verifier – if using PKCE, the code verifier string

The server will return a JSON object with your access token:

{
  "access_token": "_8ij6EICnZ8wMpWG0czn4yilNPh-F52IsBm9a5K3yYHq_6L_NGX8JfZv-xsAEA5O8_BLuEkaZJemtsbKbJ2cBg",
  "token_type": "bearer",
  "user_id": 1
}

Full client apps and old devices – password grant

TODO

Permissions

You don’t need any permissions to access public data – since basic user information includes the ActivityPub ID, all that information could be retrieved that way anyway. To access private information and perform actions on behalf of users, you will need to request one or more permissions. Each method page specifies which exact permissions you need to use it. Every write permission implies read access as well, so if your app needs to both read friend lists and add friends, you still only need to request friends.

  • friends:read – read-only access to friend requests and private friend lists
  • friends – full access to perform friends-related actions, like adding and removing friends, editig lists, on behalf of the user
  • photos:read – read-only access to all photos and photo albums available to the user, including private ones
  • photos – full access to perform photos-related actions, like creating, editing or deleting albums and photos on behalf of the user
  • account – access to edit user’s profile and change their settings
  • wall:read – read-only access to all wall posts and comments, including those in non-public groups, other people’s posts on walls whose owners limit who can see them, and followers-only posts received from other fediverse servers which support such a thing
  • wall – access to create wall posts and comments
  • groups:read – read-only access to all of the user’s groups and events, including non-public ones, and to group and event invitations
  • groups – access to join and leave groups on user’s behalf, edit the groups they manage, and invite friends to groups
  • messages:read – read-only access to user’s private messages
  • messages – access to send private messages on behalf of the user
  • likes:read – read-only access to user’s likes and bookmarks
  • likes – access to like objects on behalf of the user and add and remove their bookmarks
  • newsfeed – access to the news feeds (friends, groups, comments)
  • notifications – access to user’s notifications
  • offline – causes a permanent access token to be issued instead of a short-lived one. Intended for use with client apps where users expect to log in once and stay logged in forever

Using an access token

To issue an authenticated API request, pass the access token as the access_token parameter, or add it as a header:

Authorization: Bearer <token>