Authentication

Authentication on Frequency is done through OAuth 2.0 and supports 3 different authentication flows.

Authorization Code Flow

The authorization code flow is for exchanging an authorization code for an access token. It should be used to have users provide you with access to their accounts and your application is a web based app that can be redirected back to.

Getting an Authorization Code

Normally users would sign on to their account through your own application OAuth page, but you can also use our own request page to demo it yourself or authorize your own application.

To request this code through the web app you can go to:

https://www.frequencyapp.com/oauth/authorize?client_id=APPLICATION_ID&redirect_uri=urn:ietf:wg:oauth:2.0:oob&response_type=code

You must replace APPLICATION_ID with a registered OAuth application ID found on your account page.

When you accept the authorization you will receive a RESPONSE_CODE which you should copy for the next step.

The weird looking urn:ietf:wg:oauth:2.0:oob is there to tell the server that you want to be redirected directly to the code page, and not back to your application. If you have put in something else for your redirect path when registering your application, make sure it matches with what you put in the above link.

Exchanging the Code for a Token

Once you have acquired the authorization code from above or from a client who has signed in through OAuth on your application, you can exchange it for an access token.

# We can use the code granted in the previous step like so:
curl https://www.frequencyapp.com/api/v1/oauth/token
  -d client_id="APPLICATION_ID"
  -d client_secret="APPLICATION_SECRET"
  -d code="RETURNED_CODE"
  -d grant_type="authorization_code"
  -d redirect_uri="urn:ietf:wg:oauth:2.0:oob"

Replace APPLICATION_ID, APPLICATION_SECRET and RETURNED_CODE with values from your account page and what was returned in the previous response.

Which should return your token:

{
  "access_token": "de6780bc506a0446309bd9362820ba8aed28aa506c71eedbe1c5c4f9dd350e54",
  "token_type": "bearer", 
  "expires_in": 7200,
  "refresh_token": "8257e65c97202ed1726cf9571600918f3bffb2544b26e00a61df9897668c33a1"
}

You can view all of your access tokens from your account page.

Client Credentials Flow

The client credentials flow is used for machine to machine authentication. It should be used when you want to authenticate your server to do something on your own behalf.

Requesting an Access Token

Credentials can be requested by passing in your client ID as well as your client secret. These are both generated when you create an OAuth application and can be found on your account page.

# We can use the code granted in the previous step like so:
curl https://www.frequencyapp.com/api/v1/oauth/token
  -d client_id="APPLICATION_ID"
  -d client_secret="APPLICATION_SECRET"
  -d grant_type="client_credentials"

Which should return your token:

{
  "access_token": "de6780bc506a0446309bd9362820ba8aed28aa506c71eedbe1c5c4f9dd350e54",
  "token_type": "bearer", 
  "expires_in": 7200,
  "refresh_token": "8257e65c97202ed1726cf9571600918f3bffb2544b26e00a61df9897668c33a1"
}

Password Flow

The password flow is used when your application is not web based, but the owner of the application is also not the owner of the resource you want to access. In this case you can provide a username and password of the user who owns the resource.

Requesting an Access Token

Credentials can be requested by passing in your client ID, client secret as well as a username and password of the user who owns the resources. Your client ID and secret are both generated when you create an OAuth application and can be found on your account page.

# We can use the code granted in the previous step like so:
curl https://www.frequencyapp.com/api/v1/oauth/token
  -d client_id="APPLICATION_ID"
  -d client_secret="APPLICATION_SECRET"
  -d username="YOUR_USERNAME"
  -d password="YOUR_PASSWORD"
  -d grant_type="password"

Replace APPLICATION_ID, APPLICAITON_SECRET, YOUR_USERNAME, and YOUR_PASSWORD with your OAuth application created on your account page, and your username and password.

Which should return your token:

{
  "access_token": "de6780bc506a0446309bd9362820ba8aed28aa506c71eedbe1c5c4f9dd350e54",
  "token_type": "bearer", 
  "expires_in": 7200,
  "refresh_token": "8257e65c97202ed1726cf9571600918f3bffb2544b26e00a61df9897668c33a1"
}

Personal Access Tokens

Personal Access tokens are created by you and act as more temporary API keys. They should be used in scripts or applications where you will only be using resources from your own account, and do not need to go through creating an OAuth application.

Creating a Personal Access Token

You can easily create a personal access token by visiting your account page.

# With shell, you can just pass the correct header with each request
curl https://www.frequencyapp.com/api/v1/articles
  -u "8641fb38-294a-41d9-9591-3449dfd99910"

# If you need to authenticate via bearer auth 
# (e.g., for a cross-origin request), use:

-H "Authorization: Bearer 8641fb38-294a-41d9-9591-3449dfd99910"
# instead of -u 8641fb38-294a-41d9-9591-3449dfd99910.