Authentication
Authorization with access tokens
iMeet® Central currently only supports OAuth 2.0 Service Client authentication. User based OAuth 2.0 web flows are coming in Q3 2015.
In order to execute any API method, you must add the authorization HTTP header with the access token. In order to obtain an access token you must follow one of the authorization flows as outlined below.
For example
GET /v1/some/api HTTP/1.1 Host: edge.imeetcentral.com Authorization: Bearer <access token>
To learn more about access tokens, please see Section 1.4 of the OAuth 2 specification
Service Client Auth Flow
To get your API client_id and private key, please navigate to Company Setup > Advanced > API. Select a user that has the appropriate permissions to create accounts and workspaces. You may want to create a new user specifically for this purpose.
After clicking on “Create new Client ID,” your browser will download a file with the necessary information to create a trust relationship between this application and iMeet® Central.
The client_id and the private_key that are required to get your first tokens are provided in this file.
In order to make your first requests to the API you’ll need to create an access token. Access tokens are built with JWT. You can find more information about JWT, including client helpers for just about any language at JWT.io. Here is an example in PHP with the Firebase JWT library and the Guzzle HTTP client library.
use JWT;
use GuzzleHttp\Client;
$auth_url = 'https://oidc.imeetcentral.com/oauth2/token';
$grant_type = 'urn:ietf:params:oauth:grant-type:jwt-bearer';
$client_id = ''; // your client id
$key = ''; // your private key
$payload = [
"iss" => $client_id,
"aud" => 'oidc.imeetcentral.com',
"exp" => time() + 600000,
"iat" => time(),
"scp" => 'cd.user'
];
$auth_token = JWT::encode($payload, $key, 'RS256');
$access_token = null;
$form_params = [
'grant_type' => $grant_type,
'assertion' => $auth_token
];
$client = new Client();
$http_response = $client->post(
$auth_url,
['Content-Type' => 'application/json'],
json_encode($form_params)
);
$json_response = json_decode($http_response->getBody()->getContents());
$access_token = $json_response->access_token;
echo "Your access token is $access_token";
In this case, the JWT payload acts as a request for an access token.
“iss” is the issuer (that’s you!), or more specifically your “client_id” that you created in the administrators interface.
“aud” is us, or more specifically, the name of the server that is handling the authentication. oidc.imeetcentral.com in this example.
“exp” is the time THIS REQUEST for an access token expires.
“iat” is is “issued at time”. That is right now. It’s important that the clock on your computer is right, otherwise, these requests may fail.
“scp” is scope, these are the permissions you are requesting that go along with the access token. For now, support for fine grained permissions is not available. This will change in the future.
Next we sign the request to make sure it originates from the client you claim it does. We do this by hashing the JSON payload with your private key.
After you send this entire JWT to the token endpoint, you get back a token.
Keep this token around, this is your access token. You’ll need to add this as an ‘Authorization’ header to all requests to the API to get access.
Your access token has a finite life. You’ll need to get a new one from time to time. The number of seconds this token is good for is included in the response with your token.
Refresh Tokens
In some circumstances, it’s beneficial to request get a new access token with a refresh token instead of completely reauthorizing the user.
Refresh tokens are currently not implemented in this API.
To learn more about refresh tokens, please see Section 1.5 of the OAuth 2 specification