COA API Basics

API Methods

Method NameAccess URIMethodsDescription
get_applicationintellivoid/v1/coa/applicationGETPOSTReturns Public Information about the Application via a Application ID
request_authenticationintellivoid/v1/coa/auth/request_authenticationGETPOSTRequests authentication by obtaining a Request Token using this method
process_authenticationintellivoid/v1/coa/auth/process_authenticationGETPOSTProcesses the authentication request, if successful it will return an Access Token and it's information
get_access_tokenintellivoid/v1/coa/auth/get_access_tokenGETPOSTReturns information about an existing Access Token

API Authentication

All these API methods except for get_application requires authentication using your Application ID and Secret Key

The following authentication methods are available
  • Basic HTTP Authentication
  • GET/POST Parameter

Basic HTTP Authentication

You can authenticate by providing your Application ID via the username field and your Secret Key via the password field

GET/POST Parameter

You can provide your authentication details via a GET Parameter or within a POST (multipart/form-data), the parameter names that is applicable to both methods is application_id for your Application ID and secret_key for your secret key

Troubleshooting

All API responses returns a X-Request-ID header with a unique value set with every response you get. It is important to log this request ID if you encounter unexpected issues and server-side errors. Intellivoid can use this ID to get more details about the request and troubleshoot the error.

Data protection

To protect your data, we do not store the information our server returns to your client, the only data we keep track of is the request data you sent and server-side details that are not visible in the request such as exception dumps, cache information and so on. This information is automatically deleted from our server after two weeks. This data is used to troubleshoot any problems with our services and to address them accordingly.

COA Error Codes

Many things can go wrong when making a request to Intellivoid's services API. Each service has it's own set of error codes. Whenever success is false a error object is returned within the results which contains a type property followed by a error_code and message property. the type property shows you what service is reporting the error. You can learn more about this in Intellivoid - Error Codes to be able to identify the error correctly.

The table below will show all the possible error codes and explain what do they mean. Additionally not all error codes will be returned on the API and some are specific to the front-end for the user, the two sets are separated.

All errors related to COA will have the type COA as shown below
{
  "success": false,
  "response_code": 500,
  "error": {
    "error_code": -1,
    "message": "INTERNAL SERVER ERROR",
    "type": "COA"
  }
}

COA Error codes (Client-side)

These are errors that you would receive on COA's API, your client should expect these errors.

Error CodeMessageObsoleteDescription
-1INTERNAL SERVER ERRORfalseAn unexpected server error occurred, this may be a bug. These types of errors are unexpected therefore it should be reported to support
1MISSING PARAMETER 'application_id'falseThis error is raised when the client fails to provide the required ‘application_id’ parameter.
2INVALID APPLICATION IDfalseThis error is raised when the client provides a Application ID that isn’t valid
3APPLICATION SUSPENDEDfalseThe Application is suspended by the service provider
4APPLICATION SUSPENDEDfalseThe Application is currently unavailable either from the service provider or the owner of this Application
6MISSING PARAMETER ‘redirect’falseThis error is raised when the client fails to provide the required ‘redirect’ parameter when trying to request authentication to an Application that uses the “Redirect” authentication method
16INVALID REDIRECT URLfalseThis error raises when the client provides a ‘redirect’ parameter containing a value that is not a valid URL. For example (https://example.com/) is valid but (foobar) is not.
19AUTHENTICATION ACCESS DOES NOT EXISTfalseThe client provided an Authentication Access Token which does not exist with the service provider
20ALREADY AUTHENTICATEDfalseThe client is attempting to generate a Authentication Access Token using a Authentication Request Token which has already been used to create an Authentication Access Token. This process can only be done once, if you lose the Authentication Access Token then you must request Authentication to the user again.
21INTERNAL SERVER ERROR WHILE TRYING TO AUTHENTICATE USERfalseThis error is raised when an unexpected error is raised when the service provide was trying to authenticate the user with your Application, this incident should be reported to support.
22MISSING PARAMETER ‘secret_key’falseThis error is raised when the client fails to provide the required ‘secret_key’ parameter.
23ACCESS DENIED, INCORRECT SECRET KEYfalseThe client’s access has been denied by the service provider for failing to provide the correct secret key that’s associated with the Application ID.
24MISSING PARAMETER ‘access_token'falseThis error is raised when the client fails to provide the required ‘access_token’ parameter.
25ACCESS DENIED, INCORRECT ACCESS TOKENfalseThis error happens when the client provides an Access Token which is invalid
26ACCESS DENIED, ACCOUNT NOT FOUNDfalseThis error happens when the account was deleted from the server either by the service provider or the user
27ACCESS TOKEN EXPIREDfalseThe Access Token has expired due to lack of activity, the client must request authentication again and retrieve a new Access Token
28ACCOUNT SUSPENDEDfalseThe user’s account has been suspended by the service provider and is no longer available
29ACCESS DENIED, USER DISABLED ACCESSfalseThe user revoked access to the Application, the Application must request authentication again.
30ACCESS DENIED, INSUFFICIENT PERMISSIONSfalseThe client has insufficient permissions to request access to this resource that it’s requesting
34REQUEST TOKEN EXPIREDfalseDue to user inactivity, the request token has expired and the Application must request authentication again
35UNSUPPORTED APPLICATION AUTHENTICATION TYPEfalseThe service provider no longer supports this Application Authentication Type and the administrator of this Application must update their Authentication Type and their client to support it
39MISSING PARAMETER ‘request_token’falseThis error is raised when the client fails to provide the required ‘request_token’ parameter.
40INVALID REQUEST TOKENfalseThis error is raised when the client provides an invalid Request Token
41AWAITING AUTHENTICATIONfalseThis isn’t an error, but rather a status-type error which indicates that the service provider is waiting for the user to authenticate. This will eventually result in an access token being granted or the request token being expired. The client should poll this request until a result has been returned.
51ACCESS DENIED DUE TO SECURITY ISSUESfalseThe service provider may deny access to a users account when it believes the user’s security is at risk and the user must review their account in order to fix this issue, this can range from Government-backed attacks to a compromised account

COA Error codes (Frontend)

These are errors that a user would receive on the front-end when using the authentication prompt. These are errors your client doesn't need to expect or handle.

Error CodeMessageObsoleteDescription
5CANNOT VERIFY CLIENT HOSTfalseWhen the user attempts to authenticate using the service providers authentication prompt this error will raise if the provider cannot verify the client’s host/device due to encryption issues or a outdated web browser
7MISSING PARAMETER ‘auth’ IN AUTH PROMPTfalseThe Web Authentication Prompt requires a “auth” parameter to verify the integrity of the request. This is provided by the Service Provider automatically when requesting authentication via COA
8MISSING PARAMETER ‘application_id’ IN AUTH PROMPTfalseThe Web Authentication Prompt requires a “application_id” parameter to verify the request authentication token.
9MISSING PARAMETER ‘request_token’ IN AUTH PROMPTfalseThe Web Authentication Prompt requires a “request_token” to verify the authentication request with the Application.
10INVALID APPLICATION ID IN AUTH PROMPTfalseThe Web Authentication Prompt will fail if Application ID is invalid
11INTERNAL SERVER ERROR IN AUTH PROMPT (TYPE PROMPT-01)falseThere was an internal server error regarding the Web Authentication Prompt, Type PROMPT-01 defines the type of prompt that was being shown to the user for troubleshooting purposes
12INVALID REQUEST TOKEN IN AUTH PROMPTfalseThis error is raised when the Web Authentication Prompt cannot verify the request token and or is considered invalid
13INTERNAL SERVER ERROR IN AUTH PROMPT (TYPE PROMPT-02)falseThere was an internal server error regarding the Web Authentication Prompt, Type PROMPT-02 defines the type of prompt that was being shown to the user for troubleshooting purposes
14MISSING PARAMETER ‘redirect’ IN AUTH PROMPTfalseThe Web Authentication Prompt requires a “redirect” parameter for Applications requesting authentication using the redirect method
15UNSUPPORTED APPLICATION TYPEfalseThis error happens when an Application Authentication Type is not supported by the Authentication Prompt, see the documentation on how to use your Application’s authentication type
17MISSING PARAMETER ‘verification_token’ IN AUTH PROMPT->ACTIONfalseThe Web Authentication Prompt will fail if the parameter ‘verification_token’ is missing, this is automatically provided by the Service Provider but will fail
18CANNOT VERIFY REQUEST, INVALID VERIFICATION TOKENfalseThe Web Authentication Prompt cannot verify the Verification Token and will not proceed due to security reasons, the user should attempt request authentication with the Application again.
31MISSING PARAMETER ‘field’falseThis error raises when COASniffle fails to provide the required ‘field’ parameter.
32MISSING PARAMETER ‘value’falseThis error raises when COASniffle fails to provide the required ‘value’ parameter.
33MISSING PARAMETER 'first_name'falseThis error raises when COASniffle fails to provide the required ‘first_name’ parameter.
36CRYPTO ERROR, APPLICATION CERTIFICATE MISHAPfalseThis error is a error related to COASniffle’s internal Application Certificate used for Intellivoid’s builtin Applications
37CRYPTO ERROR, APPLICATION REQUEST MISHAPfalseThis error is a error related to COASniffle’s internal client responsible for communicating with Intellivoid’s internal services
38ACCESS DENIEDfalseGeneric Access Denied error related to COASniffle’s internal server client
42MISSING PARAMETER ‘plan_name’falseThis error raises when COASniffle fails to provide the required ‘plan_name’ parameter, this is related to handling subscriptions
43SUBSCRIPTION PLAN NOT FOUNDfalseThe service provider failed to find the subscription plan that COASniffle requested.
44SUBSCRIPTION PROMOTION NOT FOUNDfalseThe service provider failed to find the subscription promotion code that COASniffle requested.
45SUBSCRIPTION PLAN NOT AVAILABLEfalseThe service provider found the Subscription Plan COASniffle was requesting but is currently made unavailable by the Service Provider
46SUBSCRIPTION PROMOTION NOT AVAILABLEfalseThe service provider found the Subscription Promotion COASniffle was requesting but is currently made unavailable by the Service Provider
47SUBSCRIPTION PROMOTION EXPIREDfalseThe service provider reports that the subscription promotion code that COASniffle is requesting has expired and is no longer valid
48SUBSCRIPTION PROMOTION NOT APPLICABLE TO PLANfalseThe Subscription Plan and Subscription Promotion that COASniffle provided is not valid because the promotion is not applicable to the subscription plan
49INSUFFICIENT FUNDSfalseThe user attempted to make a purchase without the sufficient funds available in the user’s account.
50MISSING PARAMETER ‘subscription_id’falseThis error raises when COASniffle fails to provide the required ‘subscription_id’ parameter.
52MISSING PARAMETER ‘application’falseThis error raises when COASniffle fails to provide the required ‘application’ parameter.
53DIRECT AUTHENTICATION IS ONLY APPLICABLE TO BULTIN APPLICATIONSfalseThis error is raised when the client attempts to tell the Authentication Prompt to directly authenticate to the user, this is not allowed for security reasons and it’s only applicable to Intellivoid’s builtin applications such as Intellivoid Suite services
54DIRECT AUTHENTICATION FAILED, APPLICATION NOT FOUNDfalseThis error is raised when the Authentication Prompt can’t find the Application that’s trying to request direct authentication