OAuth Flow

1. Redirect users to Authorization page

Redirect your users to the gpodder.net authorization page at

with the following query parameters

Name Description
client_id The client ID you received when registering your app (see Registering a Client Application).
redirect_uri The URL to which the user should be redirected after authorization.
scope A space-delimited set of Scopes which the app requests.
state An unguessable random string. It is used to protect against cross-site request forgery attacks.
response_type The string code indicating that an authorization code is requested.

2. User authenticates and authorizes your app

After logging in the user is shown an anthorization page on which the requested scopes are shown. The user can chose which scopes should be authorized, or can decline the request alltogether.

3. The user is redirected back

After successful authorization the user is redirected to the URL that was specified during registration of the app (see Registering a Client Application).

To the URL the following query parameters will be appended.

Name Description
code The authorization code that you can exchange for an access token
state The state parameter of the previous request. If this does not match, the request did not originate from gpodder.net and should not be processed.

4. Get an Access Token

You can now request an access token that can be used to access the gpodder.net API.

To retrieve the tokens, issue a POST request to

with HTTP Basic Authentication, using the client ID as username and the client secret as password.

The client MUST include the requested scopes as a query parameter. The scopes MUST NOT contain any scopes that have not previously been authorized, otherwise the request will be rejected.

The request should contain the following parameters using the application/x-www-form-urlencoded format in the body.

Name Description
grant_type The string authorization_code, indicating that an authorization code (from step 3) is exchanged for tokens
code The code value from the redirect
client_id The client ID you received when registering your app (see Registering a Client Application)

The request should include an Accept: application/json header.

The response will then contain JSON data with a access_token attributes.

The scope attribute contains the list of granted scopes.

The response will also contain a HTTP Link header) with the relation https://gpodder.net/relation/token-info. The target of this link can be used to discover the URL from which token information can be retrieved (see next step).

Link: </oauth2/token/2YotnFZFEjr1zCsicMWpAA>;
      rel="https://gpodder.net/relation/token-info"

{
   "access_token": "2YotnFZFEjr1zCsicMWpAA",
   "token_type": "bearer",
   "expires_in": 3600,
   "scope": "subscriptions suggestions"
}

5. Retrieve Token Information

information about a token can be retrieved from the token info endpoint. It’s URL SHOULD be discovered from the Link header of the response in which the token is issued (see previous step). Alternatively a client MAY chose to use the following URL

/oauth2/token/{{ token }}

The request SHOULD include an Accept: application/json header. The response will include the following information.

The information from this can be used to construct subsequent requests to the API, eg such that contain the username or app IDs.

{
    "scopes": ["subscriptions", "suggestions", "favorites"],
    "token": "2YotnFZFEjr1zCsicMWpAA",
    "app": {
        "url": "http://gpodder.org/",
        "name": "gPodder",
        "client_id": "cab216c0509f4d60b227548674694b3b",
    },
    "created_at": "2015-05-22T17:19:51Z",
    "user": {
        "login": "bob",
    }
}

6. Accessing API endpoints

Not implemented yet

7. Renew tokens

The access token has a relatively short expiration time. When the token is expired it can be renewed by repeating step 4.