Skip to main content

Quickstart

This guide explains how to:

  • Display the Agave Link front-end component in your application’s interface
  • Get an access token when your Users log into a Source System using Agave Link
  • Retrieve your User’s data from a linked Source System via Agave API

Step 1: Get Client Id and Secret

Email us at api-support@agaveapi.com to get a Client Id and Client Secret.

danger

Never include your Client Secret in your source code or send it to the front-end.

If you need to enable your front-end single-page app to make API calls independent of your backend, consider using a temporary, limited-in-scope link session instead.

Once you have a Client Id and Client Secret, you can generate a link_token. The link_token is a short-lived, single-use token used to authenticate your app with Agave Link.

Request

curl --request POST https://api.agaveapi.com/link/token/create \
--header 'API-Version: 2021-11-21' \
--header 'Client-Id: your_client_id' \
--header 'Client-Secret: your_client_secret' \
--data-raw '{
"reference_id": "user_id_in_your_app"
}'

You should use a User's ID (e.g. a username) in your application as the reference_id parameter. Using a User's ID will enable you to track which integrations your customers have enabled. For purposes of getting started, you can use "user_id_in_your_app" as your parameter. To learn more, see Reference ID.

Response

{
"link_token":"wChY253uBfrP0bBGB9fymMXMSp0auub5RmmFR33c"
}

You can initialize Agave Link using the link_token returned in Step 2. Agave Link allows your users to login to different Source Systems and generate a short-lived public_token every login.

Step 4: Get Account Token

You can use the public_token returned in Step 3 to retrieve an account_token. The account_token is a permanent token that can be used to authorize User requests to Source System's.

Note, in the example in Step 3, we display the public_token on the webpage for illustrative purposes. In your production environment, you would want to send this public_token to Agave to exchange it for an account_token. You can then store this account_token in your database and use it to access data on behalf of your Users. You should store the account_token in a secure location and never expose it to unauthorized actors (e.g. via your source code or front-end).

Request

curl --request POST https://api.agaveapi.com/link/token/exchange \
--header 'API-Version: 2021-11-21' \
--header 'Client-Id: your_client_id' \
--header 'Client-Secret: your_client_secret' \
--data-raw '{
"public_token": "public_token_from_agave_link"
}'

Response

{
"reference_id": "user_id_provided_in_step_2",
"account_token": "2FwppMpt3cQ3F7vfqQmFrITHJwhxYymtdXw6Uk0n",
"status": "linked",
"source_system": {
"slug": "procore",
"name": "Procore"
},
"linked_company": {
"id": "394e28d9-5bea-52fd-b858-1c4366fea8fe",
"source_id": "31936",
"name": "Sample Company"
},
"linked_user": {
"id": "6586d971-4562-5c82-bccf-2e7b9c968c76",
"source_id": "77742",
"name": "",
"email": "procore-user@company.com"
}
}

To learn more about Steps 2-4, see Authentication Flow.

Step 5: Read and Write Data

Now that you have an account_token, a User's account is considered Linked. You can now make requests to Agave API for that User.

Here are example API requests you can try for each Source System:

Request

curl https://api.agaveapi.com/projects \
--header 'API-Version: 2021-11-21' \
--header 'Client-Id: your_client_id' \
--header 'Client-Secret: your_client_secret' \
--header 'Account-Token: any_of_the_account_tokens'

Response

[{
"id": "ee9b53e7-f982-4be6-bc12-75f716d3ee94",
"source_id": "12345",
"address": {
"street_1": "123 Main Street",
"street_2": "Unit 1",
"city": "AnyTown",
"state": "California",
"postal_code": "19703",
"country": "USA"
},
"amount": 500000,
"completion_date": "2022-01-01",
"name": "Test Project-1",
"number": A123,
"start_date": "2022-01-01",
"status": "Active",
"type": "Residential",
"source_create_time": "2022-01-01T00:00:00.000Z",
"source_update_time": "2022-01-01T00:00:00.000Z",
"source_data": {
"@attributes": {},
"CreationDate": "2022-01-01T00:00:000Z",
"DeliveryAddressLine": [ ],
"DeliveryCity": [ ],
"DeliveryCountry": [ ],
"DeliveryPostcode": [ ],
"DeliveryState": [ ],
"FaxNumber": "11235550101",
"LogoPath": "/html/logos/aconex-stored/project/123450/2022-01-01-00-00-00-file.jpg",
"ProjectOwnerOrganizationId": "1208003047",
"ProjectOwnerOrganizationName": "AnyCompany Inc",
"PhoneNumber": "11235550100",
"PostalAddressLine": [ ],
"PostalCity": [ ],
"PostalCountry": [ ],
"PostalPostcode": [ ],
"PostalState": [ ],
"ProjectAddressLine": "123 Main Street",
"ProjectCity": "AnyTown",
"ProjectCode": "A123",
"ProjectCountry": "United States",
"ProjectDescription": "A description of the project",
"ProjectId": "12345",
"ProjectName": "Test Project-1",
"ProjectPostcode": "19703",
"ProjectShortName": "Test Project-1",
"ProjectState": "DE",
"ProjectType": "Residential",
"ProjectValue": "500000.00",
"ProjectResponsibilities": [ ],
"StartDate": "2022-01-01T00:00:000Z",
"StopDate": "2022-01-01T00:00:000Z"
}
}]

More Resources

You're all set! We hope you enjoy using Agave.