Link Session

Sometimes, you may need to enable a front-end single-page application to make independent API calls to Agave API without going through your backend.

Instead of passing Client-Id, Client-Secret, or Account-Token directly to your front-end which can compromises them to replay attacks (allowing a malicious actor to make API request on your behalf or on the behalf of your customer), you can create a temporary, limited-in-scope Link Session and pass that as the Session header to Agave APIs.

When creating a Link Session, you specify both a TTL (time-to-live; in seconds) as well as a set of "scopes" (for example, link:read means read-only access to endpoints under /link, such as /link/account and drawings:write means write access to endpoints under /drawings and /drawings/{id}/versions). The Session is only valid for the given duration and on endpoints accessible through those scopes.

For more information, see Link Session endpoint.

Example request:

Specifying a "mode":

curl --request POST 'https://api.agaveapi.com/link/sessions' \
     --header 'API-Version: 2021-11-21' \
     --header 'Content-Type: application/json' \
     --header 'Client-Id: 53b2b9cb-9828-5197-8fe8-ed91f623b135' \
     --header 'Client-Secret: bFrL8y0VRycIETBhNjHHQcWM75q74V8fBhX766uH' \
     --header 'Account-Token: 94JjjPRHAQneWNNOkXP708zta4gRk81u0bOLZUoB' \
     --data-raw '{
           "name": "file manager session",
           "ttl": "1800",
           "mode": "file-picker"
         }'

Specifying "scopes":

curl --request POST 'https://api.agaveapi.com/link/sessions' \
     --header 'API-Version: 2021-11-21' \
     --header 'Content-Type: application/json' \
     --header 'Client-Id: 53b2b9cb-9828-5197-8fe8-ed91f623b135' \
     --header 'Client-Secret: bFrL8y0VRycIETBhNjHHQcWM75q74V8fBhX766uH' \
     --header 'Account-Token: 94JjjPRHAQneWNNOkXP708zta4gRk81u0bOLZUoB' \
     --data-raw '{
           "name": "file manager session",
           "ttl": "1800",
           "scopes": [
             "link:read",
             "projects:read",
             "documents:read",
             "drawings:read",
             "specification-sections:read"
           ]
         }'

Example response:

{
    "id": "9c2f9482-210f-43a6-b39b-40ddd5f21676",
    "name": "file manager session",
    "session": "iJMLvBa5Tuyd0i2ur9FcPlE1NCM1iKzIDjX8HLwl",
    "scopes": [
        "link:read",
        "projects:read",
        "documents:read",
        "drawings:read",
        "specification-sections:read"
    ],
    "expires_at": "2022-04-11T04:06:26Z"
}

You can pass this session to the Agave File Manager component.