Login with Authly

This flow follows OAuth 2.0 and OpenID Connect. Two client types exist. Pick the one that matches your application.

  • Confidential client. Your backend keeps a secret. Use the client secret at the token step.
  • Public client. A browser app or mobile app keeps no secret. Use PKCE at the token step.

Discovery

Authly publishes a discovery document. Most client libraries read it and configure themselves.

https://api.authly.example/.well-known/openid-configuration

Scopes

You request scopes on the authorize call. Authly releases only what the user grants.

| Scope | Grants | | --- | --- | | openid | The user id. Required for OpenID Connect. | | profile | The name and avatar. | | email | The primary email and its verified flag. |

Confidential client flow

  1. Send the user to /oauth/authorize with your client_id, redirect_uri, response_type=code, scope, and a random state.
  2. The user signs in and approves. Authly redirects back with code and your state.
  3. Check that state matches what you sent.
  4. Your server posts to /oauth/token with the code and your client secret.
  5. You receive the tokens.

Public client flow with PKCE

A public client adds a code challenge. This stops an attacker from using a stolen code.

Generate a random verifier. Hash it with SHA256. Base64url encode the hash. That is your challenge.

const verifier = base64url(crypto.getRandomValues(new Uint8Array(48)));
const challenge = base64url(await sha256(verifier));

Send the challenge on the authorize call.

GET /oauth/authorize
  ?client_id=YOUR_CLIENT_ID
  &redirect_uri=https://yourapp.com/callback
  &response_type=code
  &scope=openid profile email
  &state=RANDOM
  &code_challenge=CHALLENGE
  &code_challenge_method=S256

Send the plain verifier at the token step. Send no client secret.

curl -X POST https://api.authly.example/oauth/token \
  -d grant_type=authorization_code \
  -d code=THE_CODE \
  -d redirect_uri=https://yourapp.com/callback \
  -d client_id=YOUR_CLIENT_ID \
  -d code_verifier=THE_VERIFIER

Refresh tokens

Access tokens live about fifteen minutes. When one expires, exchange the refresh token for a new pair.

curl -X POST https://api.authly.example/oauth/token \
  -d grant_type=refresh_token \
  -d refresh_token=THE_REFRESH_TOKEN \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_API_SECRET

Authly rotates refresh tokens. Each refresh returns a new one. Discard the old one. If Authly ever sees a rotated token again, it treats the token as stolen and revokes the whole session.

Multifactor authentication

Some accounts require a second factor. You do not handle this. Authly runs the second step on its hosted pages before it issues the code. If you enforce MFA on your application, open your application settings and turn it on. Users without a second factor cannot authorize your application until they add one.