Authentication

VOCUS REST APIs use basic authentication, with identity evidence sent as part of the HTTP request in the form of headers. Calls are only allowed over TLS.

Identity evidence takes the form of service account credentials. Optional headers can be added to change the scope of the call.

Remember, a service account can act on behalf of any user account or domain in its scope. Its credentials should be stored carefully.

URL	Method	Notes
https://api.polarisaerotest.com/diagnostics/echoidentity	GET	Returns identity data built from the evidence presented in the HTTP `authorization` header and any related headers.

Authenticating with a Service Account

Information is passed as the HTTP authorization header and takes the form of basic [username]:[password]. A well-formed header will include the string "basic" followed by a single whitespace and a base64 encoded string with the username, a colon, and the password.

Example: basic YV9zZXJ2aWNlX2FjY291bnQ6YV9zdHJvbmdfcGFzc3dvcmQ=

JavaScript

            var url = "https://api.polarisaerotest.com/diagnostics/echoidentity",
                username = "a_service_account",
                password = "a_strong_password",
                authorizationHeader = "basic " + btoa(username + ":" + password);

            $.ajax({
                url: url,
                headers: { Authorization: authorizationHeader },
            }).always(function(response){
                console.log(response);
            });

c#

            string url = "https://api.polarisaerotest.com/diagnostics/echoidentity";
            string username = "a_service_account";
            string password = "a_strong_password";

            var client = new RestClient( url ) {
                Authenticator = new HttpBasicAuthenticator( username, password )
            };

            var request = new RestRequest( "EchoIdentity", Method.GET, DataFormat.Json );
            var response = client.Execute( request );

            Assert.AreEqual( HttpStatusCode.OK, response.StatusCode );

Troubleshooting

Is the authorization header present and well-formed?
Are the credentials correct?
Are the credentials from the target environment (production versus staging)?
Do the credentials belong to a service account?

Impersonating a User Account

An additional header can be added to specify that the service account is making the call on behalf of a user account. Operations within the call will reflect the identity of the impersonated user, including the domain to which they belong. This is especially desirable when that user's actions initiated the call, as they will be indicated as the actor in logs, histories, notifications, etc.

JavaScript

            var url = "https://api.polarisaerotest.com/diagnostics/echoidentity",
                username = "a_service_account",
                password = "a_strong_password",
                accountId = "id-to-impersonate",
                authorizationHeader = "basic " + btoa(username + ":" + password);

            $.ajax({
                url: url,
                headers: { 
                        Authorization: authorizationHeader, 
                        Impersonation: accountId 
                    },
            }).always(function(response){
                console.log(response);
            });

c#

            string url = "https://api.polarisaerotest.com/diagnostics/echoidentity";
            string username = "a_service_account";
            string password = "a_strong_password";
            string accountId = "id-to-impersonate";

            var client = new RestClient( url ) {
                Authenticator = new HttpBasicAuthenticator( username, password )
            };

            var request = new RestRequest( "EchoIdentity", Method.GET, DataFormat.Json );
            request.AddHeader( "Impersonation", accountIdToImpersonate );

            var response = client.Execute( request );
            Assert.AreEqual( HttpStatusCode.OK, response.StatusCode );

Using an Alternate Domain

An additional header can be added to specify that the service account wishes to act against a different domain than it belongs to. This allows a single service account to manage an enterprise domain by manipulating the user accounts and tails in a specific domain, or even to create new domains. Alternate domain indication cannot be combined with user account impersonation. Impersonating a user account will always act against the domain to which that account belongs.

JavaScript

            var url = "https://api.polarisaerotest.com/diagnostics/echoidentity",
                username = "a_service_account",
                password = "a_strong_password",
                authorizationHeader = "basic " + btoa(username + ":" + password),
                alternateDomainId = "domain-id-to-use";

            $.ajax({
                url: url,
                headers: { Authorization: authorizationHeader, "Alternate-Domain": alternateDomainId },
            }).always(function(response){
                console.log(response);
            });

c#

            string url = "https://api.polarisaerotest.com/diagnostics/echoidentity";
            string username = "a_service_account";
            string password = "a_strong_password";
            string alternateDomainId = "domain-id-to-use";

            var client = new RestClient( url ) {
                Authenticator = new HttpBasicAuthenticator( username, password )
            };

            var request = new RestRequest( "EchoIdentity", Method.GET, DataFormat.Json );
            request.AddHeader( "Alternate-Domain", alternateDomainId );

            var response = client.Execute( request );
            Assert.AreEqual( HttpStatusCode.OK, response.StatusCode );

API Version 14.2.9284.29055