Open Palloo

Menu

API reference

Log in with Palloo (OAuth)

Log in with Palloo: an OpenID Connect provider for the operator's own sites. Authorization code flow with PKCE S256 only. Discovery is at /.well-known/openid-configuration. The token, userinfo and revocation endpoints answer errors in the OAuth shape (OAuthError), not Error.

These endpoints live on the issuer, https://app.palloo.app, not on the API address: take their URLs from https://app.palloo.app/.well-known/openid-configuration. Send a bot token as Authorization: Bearer palloo_bot_... unless the operation says otherwise; see Authentication.

On this page

OAuth token

POST /oauth/token OAuth app

The token endpoint: authorization_code (with code, redirect_uri and code_verifier) or refresh_token (with refresh_token and an optional narrower scope). The client authenticates with HTTP Basic (client_secret_basic) or a client_assertion (private_key_jwt), whichever it was registered with. Refresh tokens rotate: each use returns a new one, and presenting a used one revokes every token of that sign-in. Presenting a used code does the same. Errors use the OAuth shape. A palloo:admin code or refresh needs a DPoP proof (htm POST, htu the token endpoint, no ath) made with the key named by the authorization request's dpop_jkt; the tokens are then bound to that key (token_type DPoP, access tokens 5 minutes, the sign-in at most 2 hours). Any other request with a DPoP header gets invalid_dpop_proof.

Try it: not available. These endpoints are on the issuer and are called by your app, not with a bot token.

Parameters

Parameters of OAuth token
Name	In	Type	Description
DPoP	header	string

Request body

application/x-www-form-urlencoded: OAuthTokenRequest (required)

Fields of the application/x-www-form-urlencoded request body
Field	Type	Description
grant_typeRequired	string	One of `authorization_code`, `refresh_token`
code	string
redirect_uri	string
code_verifier	string
refresh_token	string
scope	string
client_id	string
client_assertion_type	string	One of `urn:ietf:params:oauth:client-assertion-type:jwt-bearer`
client_assertion	string

Responses

200

Tokens.

Body: OAuthTokens

Example response (200)

{
  "access_token": "string",
  "token_type": "Bearer",
  "expires_in": 0,
  "refresh_token": "string",
  "id_token": "string",
  "scope": "string"
}

400

invalid_request, invalid_grant, invalid_scope or unsupported_grant_type.

Body: OAuthError

401

invalid_client.

Body: OAuthError

404

oidc_disabled: Log in with Palloo is off on this instance (PALLOO_OIDC_ENABLED).

Body: Error

429

rate_limited, with Retry-After. An authenticated client has its own budget (600, then 20 a second) on the token and revocation endpoints, and each access token one at userinfo (60, then one a second). Failed client authentications and invalid access tokens count against the caller's address (60, then one every 2 seconds); once that is used up, every request from the address answers 429 until it refills. All three let requests through while the shared limiter is unreachable.

Body: OAuthError

Retry-After header.

500

server_error.

Body: OAuthError

OAuth userinfo

GET /oauth/userinfo OAuth app

The claims for an access token from the token endpoint (Authorization: Bearer), by granted scope. Suspended, deactivated, deleted or moved accounts answer 401.

Try it: not available. These endpoints are on the issuer and are called by your app, not with a bot token.

Responses

200

The claims.

Body: OAuthUserinfo

Example response (200)

{
  "sub": "string",
  "preferred_username": "string",
  "name": "string",
  "picture": "string",
  "email": "string",
  "email_verified": false,
  "palloo_instance_role": "owner"
}

401

invalid_token, with WWW-Authenticate: Bearer error="invalid_token".

Body: OAuthError

404

oidc_disabled: Log in with Palloo is off on this instance (PALLOO_OIDC_ENABLED).

Body: Error

429

rate_limited, with Retry-After. An authenticated client has its own budget (600, then 20 a second) on the token and revocation endpoints, and each access token one at userinfo (60, then one a second). Failed client authentications and invalid access tokens count against the caller's address (60, then one every 2 seconds); once that is used up, every request from the address answers 429 until it refills. All three let requests through while the shared limiter is unreachable.

Body: OAuthError

Retry-After header.

500

server_error.

Body: OAuthError

OAuth userinfo post

POST /oauth/userinfo OAuth app

The same as the GET operation.

Try it: not available. These endpoints are on the issuer and are called by your app, not with a bot token.

Responses

200

The claims.

Body: OAuthUserinfo

Example response (200)

{
  "sub": "string",
  "preferred_username": "string",
  "name": "string",
  "picture": "string",
  "email": "string",
  "email_verified": false,
  "palloo_instance_role": "owner"
}

401

invalid_token, with WWW-Authenticate: Bearer error="invalid_token".

Body: OAuthError

404

oidc_disabled: Log in with Palloo is off on this instance (PALLOO_OIDC_ENABLED).

Body: Error

429

rate_limited, with Retry-After. An authenticated client has its own budget (600, then 20 a second) on the token and revocation endpoints, and each access token one at userinfo (60, then one a second). Failed client authentications and invalid access tokens count against the caller's address (60, then one every 2 seconds); once that is used up, every request from the address answers 429 until it refills. All three let requests through while the shared limiter is unreachable.

Body: OAuthError

Retry-After header.

500

server_error.

Body: OAuthError

OAuth revoke

POST /oauth/revoke OAuth app

RFC 7009 revocation, with the same client authentication as the token endpoint. A refresh token revokes its whole sign-in; an access token only itself. Unknown tokens and tokens of other clients also answer 200.

Try it: not available. These endpoints are on the issuer and are called by your app, not with a bot token.

Request body

application/x-www-form-urlencoded: object (required)

Fields of the application/x-www-form-urlencoded request body
Field	Type	Description
tokenRequired	string
token_type_hint	string	One of `access_token`, `refresh_token`
client_assertion_type	string
client_assertion	string

Responses

200

Revoked, or nothing to revoke.

400

invalid_request.

Body: OAuthError

401

invalid_client.

Body: OAuthError

404

oidc_disabled: Log in with Palloo is off on this instance (PALLOO_OIDC_ENABLED).

Body: Error

429

rate_limited, with Retry-After. An authenticated client has its own budget (600, then 20 a second) on the token and revocation endpoints, and each access token one at userinfo (60, then one a second). Failed client authentications and invalid access tokens count against the caller's address (60, then one every 2 seconds); once that is used up, every request from the address answers 429 until it refills. All three let requests through while the shared limiter is unreachable.

Body: OAuthError

Retry-After header.

500

server_error.

Body: OAuthError

OAuth end session

GET /oauth/end_session OAuth app

RP-initiated logout. Prefer the POST form, so the hint stays out of browser history. A valid id_token_hint (expired is fine, but not issued more than 30 days ago) revokes the tokens of that sign-in. The browser is sent to post_logout_redirect_uri (with state) only when it is registered for the client named by the hint or client_id; otherwise to the web client's home page. The Palloo web session is not ended.

Try it: not available. These endpoints are on the issuer and are called by your app, not with a bot token.

Parameters

Parameters of OAuth end session
Name	In	Type	Description
id_token_hint	query	string
client_id	query	string
post_logout_redirect_uri	query	string
state	query	string

Responses

302

Sent to the registered post-logout URI, or to the web client's home page.

Location header.

404

oidc_disabled: Log in with Palloo is off on this instance (PALLOO_OIDC_ENABLED).

Body: Error

429

rate_limited: too many attempts. Every operation a bot calls is also limited per bot (50 at once, then 50 per second), so any authenticated operation can answer this to a bot. Changes to a community's structure (creating or changing the community, channels, roles, member roles, overwrites, invites, kicks, bans, timeouts, report updates and actions, and bots) are also limited per caller (30 at once, then 1 per second) and per community (60 at once, then 1 per second), and creating communities per caller (10 at once, then 1 every 5 minutes).

Body: Error

Retry-After header.

OAuth end session post

POST /oauth/end_session OAuth app

The same as the GET operation, with the parameters as a form.

Try it: not available. These endpoints are on the issuer and are called by your app, not with a bot token.

Request body

application/x-www-form-urlencoded: object (required)

Fields of the application/x-www-form-urlencoded request body
Field	Type	Description
id_token_hint	string
client_id	string
post_logout_redirect_uri	string
state	string

Responses

302

Sent to the registered post-logout URI, or to the web client's home page.

Location header.

400

invalid_request: the body is not a form.

Body: OAuthError

404

oidc_disabled: Log in with Palloo is off on this instance (PALLOO_OIDC_ENABLED).

Body: Error

429

rate_limited: too many attempts. Every operation a bot calls is also limited per bot (50 at once, then 50 per second), so any authenticated operation can answer this to a bot. Changes to a community's structure (creating or changing the community, channels, roles, member roles, overwrites, invites, kicks, bans, timeouts, report updates and actions, and bots) are also limited per caller (30 at once, then 1 per second) and per community (60 at once, then 1 per second), and creating communities per caller (10 at once, then 1 every 5 minutes).

Body: Error

Retry-After header.