OAuth2 for third-party apps

OAuth2 with PKCE flow for third-party apps and multi-user integrations — via the footage.one Keycloak realm.

When OAuth2 instead of an API token?

Scenario Recommendation
Personal agent (Claude Desktop, own n8n) API token
Third-party app with multiple end users OAuth2 / PKCE
Custom GPT with Actions OAuth2 (required by OpenAI)

Flow

footage.one uses Authorization Code Flow with PKCE — suitable for public clients (SPAs, mobile, desktop) and confidential clients (server).

1. App opens auth URL with code_challenge
2. User signs in at Keycloak
3. Callback returns code
4. App exchanges code + code_verifier for tokens
5. Access token → Authorization header for /api/asset/

Endpoints

footage.one uses Keycloak. Realm: footageone. The Asset Manager app itself runs at https://app.footage.one and authenticates against the same realm.

  • Issuer: https://auth.footage.one/realms/footageone
  • OIDC Discovery: https://auth.footage.one/realms/footageone/.well-known/openid-configuration — provides all endpoint URLs, supported scopes and signing keys in machine-readable form.
  • Authorize: https://auth.footage.one/realms/footageone/protocol/openid-connect/auth
  • Token: https://auth.footage.one/realms/footageone/protocol/openid-connect/token
  • Userinfo: https://auth.footage.one/realms/footageone/protocol/openid-connect/userinfo

For most OAuth2 libraries the issuer is sufficient — endpoints are automatically loaded via discovery.

Scopes

Scope Meaning
openid Required — OIDC conformity
profile User profile data
email Email address

Resource-specific scopes (assets:read, albums:write, …) are not currently implemented — the access token reflects the permissions of the signed-in user.

Client registration

OAuth clients are registered via footage.one support — no self-service. Request with the following information:

  • Name of the third-party app
  • Redirect URIs (multiple allowed)
  • Public or confidential client?
  • Description of the use case

You will then receive a client_id (and client_secret for confidential clients).

Next steps

API tokensCookbook