# 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:**


```json
{
    "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:**


```json
{
    "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):**


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

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


```js
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:**


```json
{
"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:**


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

**Example Request:**


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