Authentication

Authentication is a critical component of interacting with the BillingPlatform API. This chapter will guide you through the two authentication mechanisms supported by the API, ensuring secure and authorized access to your data.

Authentication Overview

BillingPlatform supports two methods of authentication to ensure secure access to your data:

Obtain a Session ID with a POST Call

Obtaining a session ID is a straightforward way to secure your API requests. This method involves making a POST request to the authentication endpoint with your credentials to receive a session ID, which you include in subsequent requests.

Steps to Obtain a Session ID

1. Get a BillingPlatform Account with API Access: How to validate that your BP user account has API access. Add screen shots allow API.
2. Generate Session ID with Login call: Ensure you have your username and password ready.

Making the POST Call

To obtain a session ID, make a POST request to the authentication endpoint with your username and password.

Login Call URL:

https://my.billingplatform.com/myorg/rest/2.0/login

Example Request Payload:

{
    "username": "my.username",
    "password": "password"
}

Handling the Response

If the credentials are valid, the response will include a session ID that you can use for subsequent API requests.

Example Response:

{
    "loginResponse": [
        {
            "SessionID": "thisWillBeAStringOfCharacters",
            "ErrorCode": "0",
            "ErrorText": []
        }
    ]
}

Using the Session ID

Include the session ID in the Authorization header of each API request. The session ID should be prefixed with sessionid .

Example API Request with Session ID (cURL):

curl --location 'https://{env}.billingplatform.com/{org}/rest/2.0/ACCOUNT/12345' \
--header 'sessionid: thisWillBeAStringOfCharacters' \
--data ''

Example API Request with Session ID (JavaScript, Fetch):

const myHeaders = new Headers();
myHeaders.append("sessionid", "thisWillBeAStringOfCharacters");

const raw = "";

const requestOptions = {
    method: "GET",
    headers: myHeaders,
    body: raw,
    redirect: "follow"
};

fetch("https://{env}.billingplatform.com/{org}/rest/2.0/ACCOUNT/12345", requestOptions)
    .then((response) => response.text())
    .then((result) => console.log(result))
    .catch((error) => console.error(error));

Securing Your Session ID

To ensure the security of your session ID, follow these best practices:

• Keep It Secret: Never share your session ID publicly or embed it directly in client-side code.
• Monitor Usage: Regularly monitor API usage to detect any unusual or unauthorized activity.

Error Handling

If your session ID is missing or invalid, the API will return an authentication error. Handle these errors gracefully in your application to provide a better user experience.

Example Error Response:

{
"error": "unauthorized",
"message": "Invalid session ID"
}

Logging Out

When you are finished with your session, you should log out to invalidate the session ID. This is done via a POST request to the logout endpoint.

Logout Call URL:

https://my.billingplatform.com/myorg/rest/2.0/logout

Example Request:

POST /rest/2.0/logout HTTP/1.1
Host: api.billingplatform.com
Authorization: Session YOUR_SESSION_ID