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 Agave Link
  • Retrieve your User’s data from a linked 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 believe your Secret has been compromised, please contact us immediately at security@agaveapi.com.

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 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 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.