Skip to main content

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.