Authentication

The BiG EVAL REST API uses OAuth 2.0 to authenticate and authorize access to resources. This means, that when an API client wants to interact with resources, it first needs to authenticate. It then receives an Access Token that can be sent with every request to resources. The IdentityServer checks the validity of the Access Token to either allow or deny the request.

Registering an API Client

Before you can request an Access Token, you’ll need to register your API client (e.g. your PowerShell-Script, application, package etc.) in BiG EVAL. Every registered OAuth client is assigned a unique Client ID and a Client Secret that is needed to request the Access Token.

Requesting an Access Token

An API Client needs to request an Access Token by presenting its Client ID and Client Secret in the body of an HTTP POST request to the Identity Server. If they are correct and access is allowed, the IdentityServer returns the requested Access Token to the Client.

URL
https://mybigevalserver/connect/token

Verb:
POST

Content-Type:
application/x-www-form-urlencoded

Body:
grant_type=client_credentials&scope=bigeval-api-v1&client_id=e01b7ba2dd930ea97da79b0005341ee0&client_secret=5d1b205aae2d4fec90d424469a3f88ac

{
    "access_token": "628aa2ab34cbcd5d628ac95caee210336dce5a9ff6cdb3956faaf6f403fc75e4",
    "expires_in": 62208000,
    "token_type": "Bearer",
    "scope": "bigeval-api-v1"
}

# Defines the base-url of the BiG EVAL API and instance
$bigevalUrl = "https://mybigevalserver/"

# The Client ID of the API Client.
$clientId = "e01b7ba2dd930ea97da79b0005341ee0"

# The Client Secret of the API Client.
$clientSecret = "5d1b205aae2d4fec90d424469a3f88ac"

# Get OAuth2 Access-Token
[string]$accessToken = $null
try {
  $tokenEndpoint = $bigevalUrl+"connect/token"
  $authBody = "grant_type=client_credentials&scope=bigeval-api-v1&client_id=" + $clientId + "&client_secret=" + $clientSecret
  $authResponse = Invoke-RestMethod -Uri $tokenEndpoint -Method POST -Body $authBody
  $accessToken = $authResponse.access_token
  $accessTokenExpiresAt = (Get-Date).AddSeconds($authResponse.expires_in)
  Write-Host "OAuth Token Request successful"
  Write-Host " Token expires at:" $accessTokenExpiresAt
} catch {
  Write-Host "OAuth Token Request failed"
  Write-Host " StatusCode:" $_.Exception.Response.StatusCode.value__
  Write-Host " StatusDescription:" $_.Exception.Response.StatusDescription
} 

Lifetime of an Access Token

Every Access Token has a lifetime of 90 days. During this period of time, the same Access Token can be used over and over again. Requesting a new Access Token is not needed. If the 90 days are over, the Access Token gets invalid and a new Access Token must be requested.

Using the Access Token in an API requeest

Every REST API request needs a valid Access Token in the HTTP-Header. Otherwise it gets rejected by the IdentityServer.

Add a HTTP-Header with the Name “Authorization” and the Value “Bearer {AccessToken}” to the HTTP-Request. Whereas the placeholder {AccessToken} (including the curly brackets) should be replaced by your Access Token.

Fore example:

Authorization:Bearer 123123123123