Last updated: 2024-11-14

Personal access token

---

The personal access tokens (PAT) can be used for accessing the ShareAspace REST APIs, impersonating the users that created the token. These tokens can be used instead of using the JWT access tokens retrieved via OAuth 2.0 flows.

Typically the personal access tokens would be used for integration scenarios or when connecting to ShareAspace with external tools that do not allow for user interactive OAuth 2.0 authorization/authentication.

• A personal access token has a set time limit. Once the time limit is passed the token can no longer be used. An email will be sent out to the user that created the token when the token is 2 days away from expiring.
• An issued personal access token can be revoked at any time by the user that created it.
• An issued personal access token can have its time limit modified.
• When a personal access token is created an email notification will be sent to the user creating the token.
• The personal access token is passed as a Basic Authorization header when used with the API.
  • The value of the Authorization header is "Basic {base64 encoded string}. The base 64 encoded string should be the encoding of: ":{pat}" (e.g. ":xyzWEa...").
• When bootstrapping a collection a PAT will be created for the collection administrator. The PAT will be provided by the collection bootstrap tool.

Note

ShareAspace will only provide the PAT value when it is first created. The PAT is not stored in ShareAspace so there is no way of getting the value for a specific PAT at a later time.

Important

The PAT should be kept secret and handled with care.

PowerShell example, PAT used for getting the default information filter settings via the API

$pat = "xyzWEa..."

$authHeader = @{ 
    "Authorization" = ("Basic", [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes(("", $pat -join ":"))) -join " ") 
}

$requestUri = "https://xyz.eurostep.com/api/space/myspace/informationFilter"

$response = Invoke-RestMethod -Method Get -Uri $requestUri -ContentType "application/json" -Headers $authHeader

Token notifications

---

The from address used in emails sent for token notifications can be updated via the collection API.

HTTP PUT /collection/setting/{id}

where {id} in this case is "personalAccessToken".

Request body:

{
    "fromAddress": "_FROM_ADDRESS_"
}

---