ATLAS FormBuilder - Data Endpoint Access Token Management

This document provides an in-depth explanation of how to manage the Data Endpoint access tokens of a FormBuilder form.

Data Endpoints provide a way to retrieve formatted, tabular data for your form responses. To make access easier than the basic authentication required by the REST webservices, data endpoints can be accessed using access tokens as a bearer token in the HTTP Authorization header.

Generating Access Tokens

Token Lifespans

Access tokens support three expiration periods:

One Month - Token expires 30 days from creation.
Three Months - Token expires 90 days from creation.
Six Months - Token expires 180 days from creation.

Maximum Token Limit

You can have a maximum of three active access tokens per data endpoint at any time. When you attempt to create a new token that would exceed this limit, the system will prevent the operation and require you to delete or rotate an existing token first.

Creating Tokens via the User Interface

To create a new access token through the FormBuilder interface:

Navigate to Export Data from the form menu
Select Manage Data Endpoints
Click Edit on the specific data endpoint you want to create a token for
In the Access Tokens section, click Create New Token
Select your desired expiration period (One Month, Three Months, or Six Months)
Specify the owner and technical contact email address
The system will generate a new token that you can copy and use immediately

Creating Tokens via API

Access tokens can be programmatically managed through the REST API. All token operations require authentication using AD account credentials for an account with FormGroupAdmin privileges.

Prerequisites

Valid AD account with FormGroupAdmin permissions
Basic HTTP Authentication credentials
The data endpoint ID for which you want to create a token

CURL Example Notation

The CURL examples in this section use the following placeholders:

https://appserv7.admin.uillinois.edu/FormBuilderService - Replace with the base URL of your FormBuilder instance
username:password - Replace with your AD account credentials
550e8400-e29b-41d4-a716-446655440000 - Replace with your actual data endpoint ID (GUID)
660e8400-e29b-41d4-a716-446655440001 - Replace with your actual access token ID (GUID)

Creating a New Token

To create a new access token, POST to the following endpoint with the data endpoint ID:

POST /api/endpoint/{dataEndpointId}/accessTokens

Parameters:

ownerUinOrPrincipalName - The UIN or Active Directory principal name of the token owner
technicalContactEmailAddress - The email address of the technical contact responsible for this token
expiration - The desired expiration period (OneMonth, ThreeMonth, or SixMonth)

The response will include the newly created access token. The token will not be retrievable again from the system after creation.

Example - Creating New Token

curl -X POST "https://appserv7.admin.uillinois.edu/FormBuilderService/api/endpoint/550e8400-e29b-41d4-a716-446655440000/accessTokens?ownerUinOrPrincipalName=user@illinois.edu&technicalContactEmailAddress=admin@illinois.edu&expiration=OneMonth" \
  --header "X-Api-Version:1" \
  -u "username:password"

Managing Tokens

Viewing Access Tokens

To see all access tokens for a data endpoint, send a GET request to:

GET /api/endpoint/{dataEndpointId}/accessTokens

This returns a list of all active tokens for the endpoint, including expiration dates and owner information.

Example - Viewing Access Tokens

curl -X GET https://appserv7.admin.uillinois.edu/FormBuilderService/api/endpoint/550e8400-e29b-41d4-a716-446655440000/accessTokens \
  --header "X-Api-Version:1" \
  -u "username:password"

Example Response:

[
    {
        "OwnerUIN": "123456789",
        "OwnerDisplayName": "Example User",
        "TechnicalContactEmailAddress": "exampleuser@illinois.edu",
        "Token": "JpsyZV9O1WTZq7G0",
        "DataEndpointId": "550e8400-e29b-41d4-a716-446655440000",
        "ExpirationUtc": "2026-07-06T14:20:54.6688283Z",
        "Id": "660e8400-e29b-41d4-a716-446655440001"
    }, {
        "OwnerUIN": "123456789",
        "OwnerDisplayName": "Example User",
        "TechnicalContactEmailAddress": "exampleuser@illinois.edu",
        "Token": "TMXqxIu5OHuhwbrSR",
        "DataEndpointId": "550e8400-e29b-41d4-a716-446655440000",
        "LastUsageUtc": "2026-01-08T20:41:00.4654276Z",
        "ExpirationUtc": "2026-07-06T14:21:17.6425288Z",
        "Id": "641bafa5-beff-454c-96f0-b3ca11ec8fbe"
    }
]

Deleting Tokens

To remove an access token, send a DELETE request to:

DELETE /api/endpoint/{dataEndpointId}/accessTokens/{accessTokenId}

Deleting a token removes access for that token without affecting other active tokens.

Example - Deleting Tokens

curl -X DELETE https://appserv7.admin.uillinois.edu/FormBuilderService/api/endpoint/550e8400-e29b-41d4-a716-446655440000/accessTokens/660e8400-e29b-41d4-a716-446655440001 \
  --header "X-Api-Version:1" \
  -u "username:password"

Example Response:

HTTP/2 204 No Content

Rotating Tokens Automatically

The ExchangeAccessToken function automatically rotates tokens while preserving ownership information:

POST /api/endpoint/{dataEndpointId}/accessTokens/exchange

Parameters:

expiration - The expiration period for the new token (OneMonth, ThreeMonth, or SixMonth)

Example - Token Exchange

curl -X POST "https://appserv7.admin.uillinois.edu/FormBuilderService/api/endpoint/550e8400-e29b-41d4-a716-446655440000/accessTokens/exchange?expiration=ThreeMonth" \
  --header "X-Api-Version:1" \
  -u "username:password"

Example Response:

{
    "OwnerUIN": "123456789",
    "OwnerDisplayName": "Example User",
    "TechnicalContactEmailAddress": "exampleuser@illinois.edu",
    "Token": "AbMqazmpOrAnOoR7x",
    "DataEndpointId": "550e8400-e29b-41d4-a716-446655440000",
    "ExpirationUtc": "2026-04-21T17:50:29.17101Z",
    "Id": "ff9cd31c-7d4f-4d60-8541-b3d911260491"
}

How Token Exchange Works

The exchange operation:

Creates a new token with the specified expiration period, copying the owner and technical contact information from an existing token
Copies ownership information - The new token has the same owner and technical contact details as the existing tokens
Removes oldest token if at limit - If there are already three active tokens, the exchange operation deletes one token when creating the new one

Automatic Token Eviction

When the exchange operation needs to make room for a new token, it selects a token for deletion using the following priority:

Expired tokens - If any tokens have passed their expiration date, the oldest expired token is deleted
Token with nearest expiration - If no tokens are expired, the token with the nearest expiration date is deleted Data Endpoints provide a way to retrieve formatted, tabular data for your form responses. To make access easier than the basic authentication required by the REST webservices, data endpoints can be accessed using access tokens as a bearer token in the HTTP Authorization header.

Generating Access Tokens

Token Lifespans

Access tokens support three expiration periods:

One Month - Token expires 30 days from creation.
Three Months - Token expires 90 days from creation.
Six Months - Token expires 180 days from creation.

Maximum Token Limit

Creating Tokens via the User Interface

To create a new access token through the FormBuilder interface:

Navigate to Export Data from the form menu
Select Manage Data Endpoints
Click Edit on the specific data endpoint you want to create a token for
In the Access Tokens section, click Create New Token
Select your desired expiration period (One Month, Three Months, or Six Months)
Specify the owner and technical contact email address
The system will generate a new token that you can copy and use immediately

Creating Tokens via API

Access tokens can be programmatically managed through the REST API. All token operations require authentication using AD account credentials for an account with FormGroupAdmin privileges.

Prerequisites

Valid AD account with FormGroupAdmin permissions
Basic HTTP Authentication credentials
The data endpoint ID for which you want to create a token

CURL Example Notation

The CURL examples in this section use the following placeholders:

https://appserv7.admin.uillinois.edu/FormBuilderService - Replace with the base URL of your FormBuilder instance
username:password - Replace with your AD account credentials
550e8400-e29b-41d4-a716-446655440000 - Replace with your actual data endpoint ID (GUID)
660e8400-e29b-41d4-a716-446655440001 - Replace with your actual access token ID (GUID)

Creating a New Token

To create a new access token, POST to the following endpoint with the data endpoint ID:

POST /api/endpoint/{dataEndpointId}/accessTokens

Parameters:

ownerUinOrPrincipalName - The UIN or Active Directory principal name of the token owner
technicalContactEmailAddress - The email address of the technical contact responsible for this token
expiration - The desired expiration period (OneMonth, ThreeMonth, or SixMonth)

The response will include the newly created access token. The token will not be retrievable again from the system after creation.

Example - Creating New Token

curl -X POST "https://appserv7.admin.uillinois.edu/FormBuilderService/api/endpoint/550e8400-e29b-41d4-a716-446655440000/accessTokens?ownerUinOrPrincipalName=user@illinois.edu&technicalContactEmailAddress=admin@illinois.edu&expiration=OneMonth" \
  --header "X-Api-Version:1" \
  -u "username:password"

Managing Tokens

Viewing Access Tokens

To see all access tokens for a data endpoint, send a GET request to:

GET /api/endpoint/{dataEndpointId}/accessTokens

This returns a list of all active tokens for the endpoint, including expiration dates and owner information.

Example - Viewing Access Tokens

curl -X GET https://appserv7.admin.uillinois.edu/FormBuilderService/api/endpoint/550e8400-e29b-41d4-a716-446655440000/accessTokens \
  --header "X-Api-Version:1" \
  -u "username:password"

Example Response:

[
    {
        "OwnerUIN": "123456789",
        "OwnerDisplayName": "Example User",
        "TechnicalContactEmailAddress": "exampleuser@illinois.edu",
        "Token": "JpsyZV9O1WTZq7G0",
        "DataEndpointId": "550e8400-e29b-41d4-a716-446655440000",
        "ExpirationUtc": "2026-07-06T14:20:54.6688283Z",
        "Id": "660e8400-e29b-41d4-a716-446655440001"
    }, {
        "OwnerUIN": "123456789",
        "OwnerDisplayName": "Example User",
        "TechnicalContactEmailAddress": "exampleuser@illinois.edu",
        "Token": "TMXqxIu5OHuhwbrSR",
        "DataEndpointId": "550e8400-e29b-41d4-a716-446655440000",
        "LastUsageUtc": "2026-01-08T20:41:00.4654276Z",
        "ExpirationUtc": "2026-07-06T14:21:17.6425288Z",
        "Id": "641bafa5-beff-454c-96f0-b3ca11ec8fbe"
    }
]

Deleting Tokens

To remove an access token, send a DELETE request to:

DELETE /api/endpoint/{dataEndpointId}/accessTokens/{accessTokenId}

Deleting a token removes access for that token without affecting other active tokens.

Example - Deleting Tokens

curl -X DELETE https://appserv7.admin.uillinois.edu/FormBuilderService/api/endpoint/550e8400-e29b-41d4-a716-446655440000/accessTokens/660e8400-e29b-41d4-a716-446655440001 \
  --header "X-Api-Version:1" \
  -u "username:password"

Example Response:

HTTP/2 204 No Content

Rotating Tokens Automatically

The ExchangeAccessToken function automatically rotates tokens while preserving ownership information:

POST /api/endpoint/{dataEndpointId}/accessTokens/exchange

Parameters:

expiration - The expiration period for the new token (OneMonth, ThreeMonth, or SixMonth)

Example - Token Exchange

curl -X POST "https://appserv7.admin.uillinois.edu/FormBuilderService/api/endpoint/550e8400-e29b-41d4-a716-446655440000/accessTokens/exchange?expiration=ThreeMonth" \
  --header "X-Api-Version:1" \
  -u "username:password"

Example Response:

{
    "OwnerUIN": "123456789",
    "OwnerDisplayName": "Example User",
    "TechnicalContactEmailAddress": "exampleuser@illinois.edu",
    "Token": "AbMqazmpOrAnOoR7x",
    "DataEndpointId": "550e8400-e29b-41d4-a716-446655440000",
    "ExpirationUtc": "2026-04-21T17:50:29.17101Z",
    "Id": "ff9cd31c-7d4f-4d60-8541-b3d911260491"
}

How Token Exchange Works

The exchange operation:

Creates a new token with the specified expiration period, copying the owner and technical contact information from an existing token
Copies ownership information - The new token has the same owner and technical contact details as the existing tokens
Removes oldest token if at limit - If there are already three active tokens, the exchange operation deletes one token when creating the new one

Automatic Token Eviction

When the exchange operation needs to make room for a new token, it selects a token for deletion using the following priority:

Expired tokens - If any tokens have passed their expiration date, the oldest expired token is deleted
Token with nearest expiration - If no tokens are expired, the token with the nearest expiration date is deleted

Requirements for Token Exchange

At least one existing access token must be present on the data endpoint before using the exchange operation.

Keywords:

FormBuilder, ATLAS, data, endpoint, token, access, manage, create, generate, lifespan, limit, API, export, view, delete, rotate, automate, exchange, parameter, response, operation

Doc ID:

158033

Owned by:

Beckett A. in University of Illinois LAS

Created:

2026-01-21

Updated:

2026-01-21

Sites:

University of Illinois Liberal Arts and Sciences

0 0 Comment Suggest new doc Subscribe to changes