obtaining-an-access-token
This article is a stub. You can help the IndieWeb wiki by expanding it.
Collecting notes here before moving them to the appropriate pages.
⚠ Note: The details on this page do not seem to be up-to-date with the changes to the IndieAuth specification from 2020; see https://aaronparecki.com/2020/12/03/1/indieauth-2020 for a list of spec updates.
OAuth 2.0 defines three roles: the authorization endpoint, the token endpoint, and the resource server.
In the context of the IndieWeb, the "resource server" will most likely be your website and your micropub endpoint.
Manually obtaining your access token
You can use 
Sebastiaan Andeweg’s Homebrew Access Token to manually walk through the entire flow if you need to grab a token for yourself. (Currently doesn't support PKCE)
There is also 
Jamie Tanna's tokens-pls which performs the flow for you, and returns the token(s). This supports PKCE.
Examples
In these examples, the following URLs will be used.
The app the user is signing in to is OwnYourGram:
- client_id = https://ownyourgram.com
- redirect_uri = https://ownyourgram.com/auth/callback
The user signing in is Aaron Parecki:
In this example, Aaron has delegated authorization and token generation to separate external services:
- authorization_endpoint = https://indieauth.com/auth
- token_endpoint = https://tokens.indieauth.com/token
Aaron's micropub endpoint is on his own domain:
- Micropub Endpoint = https://aaronparecki.com/micropub
Web Sign-In Form
The app, ownyourgram.com, contains a web sign-in form prompting the user to enter their URL to sign in. Upon submitting the form, the app begins the auth process by discovering the user's endpoints.
Discovery
aaronparecki.com points to the three endpoints by specifying rel values on the index page.
<link rel="authorization_endpoint" href="https://indieauth.com/auth"> <link rel="token_endpoint" href="https://tokens.indieauth.com/token"> <link rel="micropub" href="https://aaronparecki.com/micropub">
Authorization Endpoint
The authorization endpoint is responsible for requesting authorization from the user and generating an authorization code. To start the sign-in flow, the client directs the user's browser to the authorization endpoint.
Summary
Request
Values are shown without URL encoding for readability.
https://indieauth.com/auth?me=https://aaronparecki.com/&
redirect_uri=https://ownyourgram.com/auth/callback&
client_id=https://ownyourgram.com&
state=1234567890&
scope=create&
response_type=code
Response
The authorization server presents this information to the user, and when they approve, generates an authorization code and redirects the user to the redirect URI specified.
HTTP/1.1 302 Found
Location: https://ownyourgram.com/auth/callback?code=xxxxxxxx
state=1234567890
Authorization
The authorization server should present an interface describing the request being made. It must indicate:
- The client_id making the request, which should be a valid URL
- If h-product or h-x-app markup is found when fetching client_id, verify that any u-url/u-uid property given matches the client_id, and if so display the name and logo/photo properties of the app to ease identification. Note that the client_id MUST always be verified *and* displayed prominently to prevent identity spoofing
- This is the URL of the actual application instance, not the generic product URL
- The requested scope
- May include an interface that allows the user to adjust the scope that will actually be granted
If the user approves the request, the authorization endpoint generates an authorization code and redirects the browser to the callback URL. (See authorization-endpoint for more details).
Token Endpoint
The token endpoint is responsible for issuing access tokens. The client sends the authorization code obtained in the previous step and expects to receive an access token in the response.
Summary
Request
Values are shown without URL encoding for readability.
POST https://tokens.indieauth.com/token Content-type: application/x-www-form-urlencoded grant_type=authorization_code& me=https://aaronparecki.com/& code=xxxxxxxx& redirect_uri=https://ownyourgram.com/auth/callback& client_id=https://ownyourgram.com
Response
The token endpoint verifies the authorization code and issues an access token in response. The response format should be form-encoded or JSON depending on the HTTP Accept header.
HTTP/1.1 200 OK Content-Type: application/x-www-form-urlencoded access_token=XXXXXX& scope=create& me=https://aaronparecki.com/
HTTP/1.1 200 OK
Content-Type: application/json
{
"access_token": "XXXXXX",
"scope": "create",
"me": "https://aaronparecki.com/"
}
(!) The form-encoded content type is only here for historical reasons. New code shall use JSON.
Verifying the authorization code
If your token endpoint and authorization endpoint are part of the same system, then the specific way the token endpoint verifies the authorization code is out of scope of this document. (e.g. if the token endpoint and authorization endpoint share a database, you can just look up the authorization code in the database.) If you are using separate token endpoint and authorization endpoint, then the below mechanism describes how the token endpoint can verify the authorization code since the code was generated not by the token endpoint.
The token endpoint can query the authorization endpoint to verify the auth code given. To verify the auth code, the token endpoint makes a POST request to the authorization endpoint with the following values:
POST https://indieauth.com/auth Content-type: application/x-www-form-urlencoded code=xxxxxxxx& redirect_uri=https://ownyourgram.com/auth/callback& client_id=https://ownyourgram.com
After the authorization server verifies that the redirect_uri, client_id match the code given, the response will include the "me" and "scope" values. The response should be form-encoded or JSON depending on the HTTP Accept header.
HTTP/1.1 200 OK Content-Type: application/x-www-form-urlencoded me=https://aaronparecki.com/& scope=create
HTTP/1.1 200 OK
Content-Type: application/json
{
"me": "https://aaronparecki.com/",
"scope": "create"
}
Micropub Endpoint
At this point, the client now has an access token that can be used on the user's Micropub endpoint. The Micropub endpoint will validate the access token and process the request.
See micropub for more details.