Requesting and using access tokens (Web Interface REST Service)
Access tokens allow applications to work with a Web Interface REST service:
• The application must request an access token using a user name and password that is valid for the REST service.
• The application must then use that access token with each request that it makes to the REST service.
A user name can be used to request more than one access token.
Note that that the lifespan of a token is set to 1800 seconds by default. If desired, this can be changed through the web.config file for the Web Interface website.
Requesting an access token
To enable programmatic access to a Web Interface REST service, the application must request an access token using a valid user name and password.
The following examples request an access token using the user name user123 and password 123. An application will typically prompt the user for their user name and password.
Visual Basic example
Dim request = TryCast(System.Net.WebRequest.Create("https://localhost:57850/ModelerService/auth/token"), System.Net.HttpWebRequest)
request.Method = "POST"
request.Headers.Add("username", "user123")
request.Headers.Add("password", "123")
request.Headers.Add("auth_access_type", "read")
request.ContentLength = 0
Dim responseContent As String = ""
Using response = TryCast(request.GetResponse(), System.Net.HttpWebResponse)
Using reader = New System.IO.StreamReader(response.GetResponseStream())
responseContent = reader.ReadToEnd()
End Using
End Using
JavaScript example
var request = new XMLHttpRequest();
request.open('POST', 'https://localhost:57850/ModelerService/auth/token');
request.setRequestHeader('username', 'user123');
request.setRequestHeader('password', '123');
request.setRequestHeader('auth_access_type', 'read');
request.onreadystatechange = function () {
if (this.readyState === 4) {
console.log('Status:', this.status);
console.log('Headers:', this.getAllResponseHeaders());
console.log('Body:', this.responseText);
}
};
request.send();
Data returned from an access token request
A successful request for an access token returns data in the following format.
{
"token_type":"Bearer",
"access_token":"abc123",
"auth_access_type":"read",
"expires_on":"07-01-2016 10:16:41"
}
A valid Access Token is a combination of the token_type and access_token. For example:
Bearer {abc123}
Making a REST service request using an access token
All programmatic requests must contain the following header.
Authorization: Bearer {access_token}
The following examples demonstrate use of an access token.
Visual Basic
Dim request = TryCast(System.Net.WebRequest.Create("https://localhost:57850/ModelerService/Servers"), System.Net.HttpWebRequest)
request.Method = "GET"
request.Headers.Add(HttpRequestHeader.Authorization, "Bearer {abc123}")
request.ContentLength = 0
Dim responseContent As String = ""
Using response = TryCast(request.GetResponse(), System.Net.HttpWebResponse)
Using reader = New System.IO.StreamReader(response.GetResponseStream())
responseContent = reader.ReadToEnd()
End Using
End Using
Java Script
var request = new XMLHttpRequest();
request.open('GET', 'https://localhost:57850/ModelerService/Servers');
request.setRequestHeader('Authorization', 'Bearer {abc123}');
request.onreadystatechange = function () {
if (this.readyState === 4) {
console.log('Status:', this.status);
console.log('Headers:', this.getAllResponseHeaders());
console.log('Body:', this.responseText);
}
};
request.send();
Revoking an access token
It is good practice for an application to have a way of revoking an access token, that is, logging off. It is also good progress for an application to revoke an access token when it is stopped.
To revoke an access token the header must contain the Authorization: Bearer {access_token} header and the username of the access token owner.
The following examples revoke an access token.
Visual Basic
Dim request = TryCast(System.Net.WebRequest.Create("https://localhost:57850/ModelerService/auth/token"), System.Net.HttpWebRequest)
request.Method = "DELETE"
request.Headers.Add("username", "user123")
request.Headers.Add(HttpRequestHeader.Authorization, "Bearer {abc123}")
request.ContentLength = 0
Dim responseContent As String = ""
Using response = TryCast(request.GetResponse(), System.Net.HttpWebResponse)
Using reader = New System.IO.StreamReader(response.GetResponseStream())
responseContent = reader.ReadToEnd()
End Using
End Using
JavaScript
var request = new XMLHttpRequest();
request.open('DELETE', 'https://localhost:57850/ModelerService/auth/token');
request.setRequestHeader('username', 'user123');
request.setRequestHeader('Authorization', 'Bearer {abc123}');
request.onreadystatechange = function () {
if (this.readyState === 4) {
console.log('Status:', this.status);
console.log('Headers:', this.getAllResponseHeaders());
console.log('Body:', this.responseText);
}
};
request.send();