This article outlines the essential authentication methods used by GraphStudio APIs, explains how to programmatically acquire and manage Bearer tokens using Graph Data Interface (GDI) patterns, and highlights best practices for secure and automated API access.
Overview
- Authentication Methods in GraphStudio APIs
- Bearer Token Acquisition and Usage
1. Authentication Methods in GraphStudio APIs
All API interactions with GraphStudio require proper authentication to secure access to the environment and data.
Supported Authorization Types
- BasicAuth: Simple username and password authentication.
- Bearer Token: The primary and most common method, using security tokens that grant access to specific resources.
- AWSSignature: For AWS-related authorization needs.
Bearer Token Authentication
To use Bearer tokens, first authenticate with GraphStudio or an SSO provider to obtain the token. This token must then be included in the Authorization header for all subsequent API requests:
Authorization: Bearer <token>
Arbitrary Headers
Some API calls or authentication schemes require passing additional custom headers (e.g. API keys or App IDs). These can be added via the s:header property in GDI queries or set directly in your HTTP client.
2. Bearer Token Acquisition and Usage
Automating token retrieval is critical for seamless API integration. GraphStudio supports patterns using GDI's s:HttpSource to request and manage Bearer tokens directly within queries.
Authenticating with Headers
You can send authentication requests by including credentials or keys in HTTP headers and retrieve tokens for later use.
Example GDI Query:
SERVICE TOPDOWN <http://cambridgesemantics.com/services/DataToolkit> {
?auth a s:HttpSource ;
s:url "https://contoso.com/authenticate" ; # Replace with your auth endpoint
s:header [ s:name "API-Key" ; s:value "{{@api_key}}" ] ;
s:header [ s:name "App-ID" ; s:value "{{@app_id}}" ] ;
?token xsd:string ; # Variable to capture the token
.
?data a s:HttpSource ;
s:from ?auth ; # Use token from ?auth
s:url "https://contoso.com/api/something/useful" ;
s:authorization [ a s:BearerToken ; s:token ?token ] ;
.
}
This approach allows you to authenticate, retrieve the token, and seamlessly use it for authorized API calls.
Authenticating with Request Body Content
For endpoints requiring credentials in the request body (e.g., JSON), use s:content to pass them.
Example GDI Query:
SERVICE <http://cambridgesemantics.com/services/DataToolkit> {
?auth a s:HttpSource ;
s:contentType "application/json" ;
s:content """{ "app_id" : "{{@app_id}}", "api_key" : "{{@api_key}}" }""" ;
s:mimetype "text/plain" ;
?token () ; # Capture token from response body
.
?data a s:HttpSource ;
s:from ?auth ;
s:url "https://contoso.com/api/something/useful" ;
s:authorization [ a s:BearerToken ; s:token ?token ] ;
.
}
This pattern handles more complex authentication flows where credentials must be passed as JSON payloads.
Handling Token Expiration Programmatically
Tokens often expire after a period. The above GDI patterns automatically re-request tokens when expired by re-executing the query containing the s:HttpSource authentication step. This mechanism supports continuous, automated API access without manual token refresh.
