SHARE THIS ARTICLE

API Authentication

The second tab in settings, Authentication, holds authentication settings of your API.

Authentication Settings

Authentication Types

APIMatic supports various types of authentication. The type dropdown list allows you to select one of the available authentication types. Make sure that you select the correct type of authentication when describing your API i.e. the authentication type in the API description must match with the authentication type of the API. The generated code autmatically appends any authentication information with the subsequent API requests. Details about the major authentication types we support are as follows.

No Authentication

Select this option if your API does not require any authentication. For skipping authentication only on a few of the endpoints, use the Skip Authentication option on the respective Endpoint description page.

GET /v1/Inventory HTTP/1.1
accept: application/json
user-agent: apimatic/1.0                
Host: acme.com
Connection: Keep-Alive

Basic Authentication

Basic authentication requires a username and a password to access the protected resources. When this option is used, two variables are added to the configuration file (see the contents of the generated code). When set, the values of these variables are used to sign the subsequent API requests.

GET /v1/Inventory HTTP/1.1
accept: application/json
user-agent: apimatic/1.0
Authorization: Basic PFRPRE86IFJlcGxhY2U+OjxUT0RPOiBSZXBsYWNlPg==
Host: acme.com
Connection: Keep-Alive

The corresponding Configuration class generated in C# is as follows.

using System;

namespace TestVoid.PCL
{
    public partial class Configuration
    {
        //The base Uri for API calls
        public static string BaseUri = "http://www.testvoid.com";

        //The username to use with basic authentication
        //TODO: Replace the BasicAuthUserName with an appropriate value
        public static string BasicAuthUserName = "TODO: Replace";

        //The password to use with basic authentication
        //TODO: Replace the BasicAuthPassword with an appropriate value
        public static string BasicAuthPassword = "TODO: Replace";

    }
}

Note   It is highly recommended that SSL is used to perform the underlying HTTP requests. Ensure that the base URL in the API Settings refers to a secure https URL.

OAuth 1.0

OAuth 1.0 provides authentication using cryptography hash computing method. The application developer (API Consumer) must acquire an access token by following a specific OAuth flow. When OAuth 1.0 authentication type is selected, four corresponsing variables are generated in the configuration file that must be set with the values of consumer key (OAuthClientId), consumer secret (OAuthClientSecret), access token (OAuthToken) and access token secret (OAuthTokenSecret). Using the values of said variables, out going API requests are automatically signed with the computed hash.

GET /v1/Inventory HTTP/1.1
accept: application/json
oauth_consumer_key: 5e8591e4bb604356b0b7142b2bf0ce14
oauth_nonce: 353514065
oauth_timestamp: 1399245123
oauth_signature_method: HMAC-SHA1
oauth_version: 1.0
oauth_token: 607282b31a7544818d210eaff6533a84
oauth_signature: ZYvBXrXaoFBX1ip9wYR3VhZl2H4%3D
Authorization: OAuth oauth_consumer_key="5e8591e4bb604356b0b7142b2bf0ce14",oauth_nonce="353514065",oauth_timestamp="1399245123",oauth_signature_method="HMAC-SHA1",oauth_version="1.0",oauth_token="607282b31a7544818d210eaff6533a84",oauth_signature="ZYvBXrXaoFBX1ip9wYR3VhZl2H4%3D"
user-agent: apimatic/1.0
Host: acme.com
Connection: Keep-Alive

The corresponding Configuration class generated in C# is as follows.

using System;

namespace TestVoid.PCL
{
    public partial class Configuration
    {
        //The base Uri for API calls
        public static string BaseUri = "http://www.testvoid.com";

        //The OAuth token to be set before API calls
        //TODO: Replace the OAuthToken with an appropriate value
        public static string OAuthToken = "TODO: Replace";

        //The OAuth token secret to be set before API calls
        //TODO: Replace the OAuthTokenSecret with an appropriate value
        public static string OAuthTokenSecret = "TODO: Replace";

        //The OAuth client id to be set before API calls
        //TODO: Replace the OAuthClientId with an appropriate value
        public static string OAuthClientId = "TODO: Replace";

        //The OAuth client secret to be set before API calls
        //TODO: Replace the OAuthClientSecret with an appropriate value
        public static string OAuthClientSecret = "TODO: Replace";

    }
}

Note   Currently APIMatic does not support token refresh mechanism and this must be handled by the API consumer.

OAuth 2.0

OAuth 2.0 depends on the encryption of SSL layer to simplify the authorization, therefore it can only be used when the base URL refers to a secure https URL. Similar to OAuth 1.0, the application developer (API Consumer) must acquire an access token by following a specific OAuth flow. When OAuth 2.0 authentication type is selected, a corresponsing variable is generated in the configuration file for the acquired access token. Using this value, out going API requests are automatically appended with the required authorization information.

GET /v1/Inventory HTTP/1.1
accept: application/json
Authorization: Bearer f80ff5694a454585bab0001a68ec5e9f
user-agent: apimatic/1.0
Host: acme.com
Connection: Keep-Alive

The corresponding Configuration class generated in C# is as follows.

using System;

namespace TestVoid.PCL
{
    public partial class Configuration
    {
        //The base Uri for API calls
        public static string BaseUri = "http://www.testvoid.com";

        //The OAuth 2.0 access token to be set before API calls
        //TODO: Replace the OAuthAccessToken with an appropriate value
        public static string OAuthAccessToken = "TODO: Replace";

    }
}

Note   Currently APIMatic does not support token refresh mechanism and this must be handled by the API consumer.

Custom Query

Some APIs require a custom query parameter to be passed along with an API request for the purpose of authorization. This type of authentication requires definition of one or more parameters that are to be submitted along with the API requests. There are no default parameters for this type of authentication and the user has to define these while describing their API. The corresponding variables generated in the configuration file should be set either statically or programmatically from the application code.

GET http://acme.com/v1/Inventory?cauth=4c4112e4a1ef4e0f9396dbc80a160fc8 HTTP/1.1
accept: application/json
user-agent: apimatic/1.0
Host: acme.com
Connection: Keep-Alive

The corresponding Configuration class generated for Custom Query authentication with two parameters, Username and Password, in C# is as follows.

using System;

namespace TestVoid.PCL
{
    public partial class Configuration
    {
        //The base Uri for API calls
        public static string BaseUri = "http://www.testvoid.com";

        //TODO: Replace the Username with an appropriate value
        public static string Username = "";

        //TODO: Replace the Password with an appropriate value
        public static string Password = "";
    }
}

Note   The values of the said parameters will be transmitted as query parameters with all API requests, except where the endpoint description uses the skip authentication option.

Custom Header

This type of authentication is similar to the custom query authentication method, except that the respective parameters are sent as header values rather than as query parameters. The values of the corresponding variables generated in the constants file will be transmitted as header values with all API requests, except where endpoint description uses skip authentication option.

GET http://acme.com/v1/Inventory HTTP/1.1
accept: application/json
cauth: 4c4112e4a1ef4e0f9396dbc80a160fc8
user-agent: apimatic/1.0
Host: acme.com
Connection: Keep-Alive

The corresponding Configuration class generated for Custom Header authentication with a single parameter, cauth, in C# is as follows.

using System;

namespace TestVoid.PCL
{
    public partial class Configuration
    {
        //The base Uri for API calls
        public static string BaseUri = "http://www.testvoid.com";

        //TODO: Replace the Cauth with an appropriate value
        public static string Cauth = "";

    }
}

Authentication Parameters

Authentication parameters let you list down with values all the variables that are needed for authentication with the API requests. APIMatic automatically generates the required parameters for most types of authentication in a configuration file which is deployed with the SDK. You can simply select the type of authentication and APIMatic will take care of the rest.

No Authentication Parameters Specified

Here’s a brief description of the fields available for authentication parameters:

Parameter Name

This is the name given to the parameter/variable that will be used for authentication.

Description

You can provide a brief description about the parameter here.

Value

This field will contain the value that has to be assigned to the parameter.

Here is the corresponding Configuration class generated by APIMatic with default parameters for basic authentication in a Python SDK.

class Configuration(object):
    # The base Uri for API calls
    BASE_URI = 'http://some-website.com'

    # The username to use with basic authentication
    # TODO: Replace the basic_auth_user_name with an appropriate value
    basic_auth_user_name = "TODO: Replace"

    # The password to use with basic authentication
    # TODO: Replace the basic_auth_password with an appropriate value
    basic_auth_password = "TODO: Replace"

You can override the names of these default parameters by specifying your own. You will also need to define parameters for authentication types in which no default parameters are generated (Custom Query, Custom Header etc.).

Authentication Parameters Specified

The same Configuration class generated now uses these user defined parameters instead.

class Configuration(object):
    # The base Uri for API calls
    BASE_URI = 'http://some-website.com'

    # The username for your some-website account.
    username = 'your username here'

    # The password for your some-website account.
    password = 'your password here'

Additional Headers

If you would like additional authentication headers to be added to your API requests, you can define them here. Their values will also be set in the configuration file in the generated SDKs. These headers will be sent with every API request except those for endpoints which set the skip authentication flag to true.

Authentication Headers

Here’s a brief description of the fields available for additional headers:

Header Name

This is the name given to the header that has to be added with the API request.

Description

You can provide a brief description about the header here.

Value

This field will contain the value that has to be assigned to the header. The following corresponding Configuration class is generated for a Python SDK. Note that we’re using the default parameter names in this example.

class Configuration(object):
    # The base Uri for API calls
    BASE_URI = 'http://some-website.com'

    # First auth header.
    first_auth_header = 'apimatic';

    # Second auth header.
    second_auth_header = 'cgaas';

    # The username to use with basic authentication
    # TODO: Replace the basic_auth_user_name with an appropriate value
    basic_auth_user_name = "TODO: Replace"

    # The password to use with basic authentication
    # TODO: Replace the basic_auth_password with an appropriate value
    basic_auth_password = "TODO: Replace"


Have questions? Submit a request.