OAuth Overview

The Fimfiction API makes use of OAuth2 for all of its interactions. OAuth2 offers significant advantages over OAuth1 in terms of the simplicity of implementing it.

Additionally, there are a wide array of libraries and clients that exist for this spec, making it easy to get up and running.

You can find the full spec at https://tools.ietf.org/html/rfc6749 if you want more information.

Authorisation Flow

There are several types of authorisation flow. Below you can find instructions for each type.

1. Authorisation Code (server based apps)
2. Implicit (mobile and browser apps)
3. User Credentials (unsupported)
4. Client Credentials

Security

OAuth2 is built off of the assumption that all transport will be SSL. Every request, including redirect URIs must be secured with SSL.

You must keep your client_secret safe. If you believe yours to be compromised you should regenerate it.

Authorisation Code

This is the most common type of authorisation flow. It involves redirecting a user to an authorisation page, receiving a temporary request token and exchanging it for an access token.

1. Authorisation Page

The first step in the authorisation flow is sending the user to the authorisation page for your application.

This page lets the user see what permissions you're requesting on their account and accept/cancel the authorisation as required.

This URL also requires several parameters to function:

• client_id - Your client ID you can find in Application Management.
• response_type - This must be set to "code".
• scope - Space delimited list of scopes. See the scopes page for what scopes you can supply here.
• state - Arbitrary string that you must use to verify the original redirect came from you to prevent CSRF attacks. Can also be used for keeping state between page loads.
• redirect_uri - A valid redirect URI you registered for your application. You can add valid URIs by editing your application. Redirect URIs must be https.

Example URL:

https://www.fimfiction.net/authorize-app?client_id=fWtCAG5xlLiY87y2BT_NFWOUyuDBlSTp&response_type=code&scope=read_user+write_user&state=abcdef&redirect_uri=https://www.example.com/fimfiction

2. Handle Redirect

Assuming the user accepted your authorisation request, they will be redirected to the redirect_uri you specified.

This redirect contains 2 parameters:

• code - The request token
• state - The state parameter you supplied with the request in step 1

You should check state against the value you submitted in step 1, and keep code which you will use in the next step to receive an access token.

3. Token Exchange

With this information you're now ready to receive the access token for the user.

Submit a POST request to https://www.fimfiction.net/api/v2/token with a body consisting of the following information:

• client_id - Your application ID
• client_secret - Your application secret
• grant_type - Must be set as "authorization_code"
• redirect_uri - Must match the redirect URI you provided in step 1.
• code - The request code from the previous step

The response to this request will contain your brand new, shiny access token as well as a list of scopes (incase we allow users to toggle what permissions they allow) and some basic user information which is especially useful in login flows.

Example Response:

{
	"access_token" : "abcdef",
	"token_type" : "bearer",
	"scope" : "read_user write_user",
	"user" : {
		"id" : "1",
		"name" : "knighty"
	}
}

4. Make API Calls

Now you have your access token you can make calls into the API as the authenticated user.

Your calls should include an Authorization header containing the token type and then token itself.

Example:

Authorization: Bearer abcdef

Implicit

Implicit flow is used when you cannot maintain client secrecy. This is the case for mobile and browser apps which make requests themselves and secrets would be impossible to keep secret as they'd have to be embedded in the app.

To use implicit flow you must enable it for your app by checking the "Allow Implicit" option.

1. Authorisation Page

The first step in the authorisation flow is sending the user to the authorisation page for your application.

This page lets the user see what permissions you're requesting on their account and accept/cancel the authorisation as required.

This URL also requires several parameters to function:

• client_id - Your client ID you can find in Application Management.
• response_type - This must be set to "token".
• scope - Space delimited list of scopes. See the scopes page for what scopes you can supply here.
• state - Arbitrary string that you must use to verify the original redirect came from you to prevent CSRF attacks. Can also be used for keeping state between page loads.
• redirect_uri - A valid redirect URI you registered for your application. You can add valid URIs by editing your application. Redirect URIs must be https.

Example URL:

https://www.fimfiction.net/authorize-app?client_id=fWtCAG5xlLiY87y2BT_NFWOUyuDBlSTp&response_type=code&scope=read_user+write_user&state=abcdef&redirect_uri=https://www.example.com/fimfiction

2. Handle Redirect

Assuming the user accepted your authorisation request, they will be redirected to the redirect_uri you specified.

This redirect contains 2 parameters:

• token - The request token
• state - The state parameter you supplied with the request in step 1

You should check state against the value you submitted in step 1. token is your access token you can use to make requests.

3. Make API Calls

Now you have your access token you can make calls into the API as the authenticated user.

Your calls should include an Authorization header containing the token type and then token itself.

Example:

Authorization: Bearer abcdef

Client Credentials

You can generate an access token for your app not tied to any user with client credentials.

1. Token Exchange

There's only one step to this process.

Submit a POST request to https://www.fimfiction.net/api/v2/token with a body consisting of the following information:

• client_id - Your client ID you can find in Application Management.
• client_secret - Your client secret you can find in Application Management.
• grant_type - Must be set as "client_credentials"

The response to this request will contain your access token which you can use to access the API. Access tokens do not expire so you should save it and use it for any future requests to the API.

Example Response:

{
	"access_token" : "abcdef",
	"token_type" : "bearer",
}