Note: Only Super Users can create API Applications
On the admin screen under integrations there is a section called API:
From this screen you can see all of the applications you have set up. Each application has a Name, App ID and Type.
There are two types of Applications you can make
- Public Link
- Server
A Public Link app is limited to only being able to create new Public Link Folios for the template you select, it is able to get information about lookups or field answers to fields that are on the selected template but nothing else.
A Server is an app that is only limited by the Access Rights of the Execute As user, meaning that the server application will be able to update anything that the selected user is able to do.
We recommend that you create an user with limited access rights for the application server to ensure that your application only has limited access rights.
To make a new application click on the plus. You can then give the Application a name and select the type (The Server Type may not be available on here as it has additional costs) The name is only for human readability to know what the application is used for:
For Public links you Simply choose the template the API will be able to create new Folios on
For Servers simply choose the User that the API will execute all of its requests as under Execute As (note that the history for items done by this application will use the name of the person you select here in the who column on the history tables)
After clicking create you will be shown the App ID and App Secret. Copy both of these and save them somewhere as for security purposes you will be unable to see the app secret after you close this modal
Now that you have an app you need to get an access_token which you will pass along with each request to the API - This token will expire after two hours but to get a new one you just need to resend the request and Folio will give you a new Token.
Bash
curl --data "client_id={your_app_ID}&client_secret={your_app_Secret}&grant_type=client_credentials" https://{Your Folio Url}/oauth/token
So from my example application my request would be
curl --data "client_id=bm90IGEgcmVhbCBpZCBidXQgYSBmYWtlIG9uZQ&client_secret=dGhpcyBpcyBhIGZha2Uga2V5IG5vdCBhIHJlYWwgb25l&grant_type=client_credentials" http://examplecorp.foliogrc.com/oauth/token
Powershell
Invoke-WebRequest -Uri "https://{Your Folio Url}/oauth/token" `
-Method "POST" `
-Body "client_id={ID}&client_secret={Secret}&grant_type=client_credentials"
So from my example application my request would be
Invoke-WebRequest -Uri "https://examplecorp.foliogrc.com/oauth/token" `
-Method "POST" `
-Body "client_id=bm90IGEgcmVhbCBpZCBidXQgYSBmYWtlIG9uZQ&client_secret=dGhpcyBpcyBhIGZha2Uga2V5IG5vdCBhIHJlYWwgb25l&grant_type=client_credentials"
This request will then return the following data in json format
{
"access_token": "cjgPufHmLBHpAykSVTsS3xG1SeY",
"token_type": "Bearer",
"expires_in": 7200,
"created_at": 1607301072
}
The access token is now the key that you will be using to communicate with the Folio API. The response also tells you when the token was created and when it expires - All tokens expire after 2 hours.
You can test that the token is working by making a “ping” request. The below sample request is using curl on a bash environment
|
Request |
Response |
curl 'https://examplecorp.foliogrc.com/graphql'
|
{ |
Now that you have an access token you can use that to both read and write data from Folio using the api.
If you want you can use the web interface of the api at, which also includes the documentation Explorer you can use graphiql on your sandbox environment. Please note that you will need to be a superuser to access this interface
https://{Your Sandbox Folio Url}/graphiql?access_token={access_token}
or
https://examplecorp.sandbox.usefolio.com/graphiql?access_token=cjgPufHmLBHpAykSVTsS3xG1SeY