🔓Authentication

Getting access to our API

Currently, Plannr offers two ways of authentication - both of which utilise Bearer Tokens for authenticating requests that you make. You can authenticate with our API in two ways.

Personal Access Token (Bearer)

Recommended for: Personal Use

This type of authentication can only be used with your User on Plannr and all Accounts that you are associated with. This token cannot be shared with other end-users and should only be used for personal access to the API - for example, when building an integration for your own use. Personal Access Tokens last a year and can be only generated by Plannr.

OAuth2 Authorization Code Grant

Recommended for: Integrating an app with Plannr. Sign in with Plannr. Using Plannr's data.

This type of authentication is suited for other applications creating integrations for Plannr with their software. With OAuth2, you will be able to request access to any of Plannr's Users after they have given you permission to access their data.

See this useful article from Okta (note - we are not affiliated nor use Okta's services): https://developer.okta.com/blog/2018/04/10/oauth-authorization-code-grant-type

Getting access to our API

Currently, there is no automated process to gain access to the Plannr API.

To get access, please email [e-mail] and provide the following information:

• Your Name

• Company Name

• Authentication Type You Require (See Above)

• Redirect URLs needed (if using OAuth2) (For example https://myapp.com/auth/plannr/callback)

If you are requesting a personal access token you must send an email from a trusted source, like using the same email that you registered with Plannr. This is so our team can trust who to provide API access to.

Authenticating

With Personal Access Token

After you have been given your personal access token you can use it to authenticate with Plannr by passing it into the Authorization header with the prefix of "Bearer". For example:

• Header Name: Authorization

• Header Value: Bearer YOUR-PERSONAL-ACCESS-TOKEN-HERE

Example cURL Request:

curl
--location 'https://api.plannrcrm.com/api/v1/logins' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <YOUR-TOKEN-HERE>'

With OAuth2 Authorization Code Grant

Authenticating using the OAuth2 Authorization Code Grant is slightly different. Plannr follows the OAuth2 standard so this documentation assumes you have knowledge of how this authentication method works.

Once you contact Plannr, one of the team will provide you with a Client ID and Secret.

Never expose your provided Secret to the public. Store it securely and limit access.

The OAuth authorization URL will only accept redirect URLs that you provide to Plannr. If you need any additional URLs approved, please email Plannr.

Plannr's OAuth2 server is on the same domain as the rest of the API. These are the following URLs you need:

• https://api.plannrcrm.com/oauth/authorize (For redirecting your users to get access to Plannr)

• https://api.plannrcrm.com/oauth/token (For requesting an API access or refreshing existing access tokens)

• Scopes just send: *

Example OAuth2 Authorization Code Flow

First, redirect your users to:

https://api.plannrcrm.com/oauth/authorize?response_type=code&client_id=CLIENT-IDclient-id&scope=*&redirect_uri=REDIRECT-URI&state=RANDOM-UNIQUE-STRING

Once users approve your application, they will be redirected to the redirect_uri where you will be given a "code" as a query parameter. You should also verify that the state that you included as a query parameter is the same in this stage to prevent man-in-the-middle attacks.

Next, make a POST request to https://api.plannrcrm.com/oauth/token with the Content-Type of application/x-www-form-urlencoded and you want to send the following properties:

• grant_type: "authorization_code"

• client_id: CLIENT-ID

• client_secret: CLIENT-SECRET

• redirect_uri: REDIRECT-URI

• code: CODE-RECEIVED

curl \
--request POST \
--location 'https://api.plannrcrm.com/oauth/token' \
--header 'Accept: application/json' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data 'grant_type=authorization_code&client_id=X&client_secret=X&redirect_uri=X&code=X'

After that, you will be given an access_token, refresh_token and an expiry date. The refresh token will expire after 6 months and the user will have to do steps 1-3 again.

To refresh an access token after it expires you can make the following POST request to: https://api.plannrcrm.com/oauth/token.

curl \
--request POST \
--location 'https://api.plannrcrm.com/oauth/token' \
--header 'Accept: application/json' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data 'grant_type=refresh_token&client_id=X&client_secret=X&refresh_token=X'

After you have completed the authentication process you can use the access token provided to make API calls. For example:

curl \
--location 'https://api.plannrcrm.com/api/v1/logins' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <YOUR-TOKEN-HERE>'

Postman Collection Sample

We have created a very basic Postman collection to get up and running with authentication. You can use the variables in the collection to store your Client ID and Secret.

3KB

Plannr Example Collection.postman_collection.json

Postman example collection

Recommended Reading

It is recommended to read the Making Requests section to understand how to build a request to Plannr's API. The Users, Logins, and Accounts section also explains how the API handles end-users and what Accounts the requests are made for.