# Overview: Getting Started

The Octa API provides secure, JSON-based REST endpoints that allow seamless integration with any modern programming
language or framework. Designed for flexibility and scalability, it enables developers to connect directly with Octa GST
services for tasks such as generating e-invoices & e-waybills, getting GSTIN registration information, retrieving
returns data and compliance data. With a single base URL and consistent request/response formats, the Octa API ensures a
simple, reliable, and developer-friendly experience.

All APIs can be accessed using the following base URL:

```
https://cloud.octagst.com/api/...
```

A machine-readable description of these APIs is available as an
[OpenAPI specification](https://octagst.com/openapi.json).

## Authentication

API authentication is done using the http `basic` authentication. This is done using the `Authorization` http header in
the request. This header can be constructed as follows:

- The **Key Id** and **Key Secret** are combined with a single colon `:`
- The resulting string is encoded in byte array using UTF-8 encoding
- The resulting string is encoded in base64 string
- The resulting string is prefixed with the authorization method `Basic`

For example, consider the following **Key Id** and **Key Secret**:

|            |                        |
| ---------- | ---------------------- |
| Key Id     | `z639031917648473675`  |
| Key Secret | `jTr7QLiwleNqMuiQaDtz` |

Header Value = Base64(`z639031917648473675:jTr7QLiwleNqMuiQaDtz`)  
Header Value = `ejYzOTAzMTkxNzY0ODQ3MzY3NTpqVHI3UUxpd2xlTnFNdWlRYUR0eg==`

Therefore, the `Authorization` http header would be:

```
Authorization: Basic ejYzOTAzMTkxNzY0ODQ3MzY3NTpqVHI3UUxpd2xlTnFNdWlRYUR0eg==
```

Refer to the next section for instructions on how to generate your **Key Id** and **Key Secret**.

## Generate API Key

- Login to [Octa GST](https://cloud.octagst.com)
- Go to the **API Keys** page (check the buttons on the top).
- Click on **New Key** button, accept the confirmation. This will generate a new API Key and display on screen. This key
  will be displayed only once. So please copy the **Key Id** and **Key Secret** shown on the screen.
- This **Key Id** and **Key Secret** can be configured in the ERP (or any other external system) to access Octa APIs.

## Using an API

Depending on the endpoint, the Octa API supports either `GET` or `POST` HTTP methods. All requests follow standard HTTP
conventions. For authentication, every request must include the `Authorization` header. Additional headers may be
required based on the specific API being called, as detailed in the documentation for each endpoint.

## Error Handling

When an API request cannot be processed successfully, Octa provides a clear error response to help you diagnose and fix
the issue quickly.

- Standard HTTP status codes: Any code in the 4xx or 5xx range indicates an error.
- Octa-specific error details: Additional information is returned in the response headers:
  - `Octa-ErrorCode`: A unique code identifying the type of error. (Refer
    [Octa Error Codes](/octa/docs/api/overview/error-codes))
  - `Octa-ErrorMessage`: A descriptive message explaining the reason for the failure.

## Fair Use

To protect Octa GST from abuse and ensure fair usage, the system may enforce rate limits. When a rate limit is exceeded,
the API will respond with the HTTP status code:

```
429 Too Many Requests
```

In this case, clients should implement **delays with exponential back-off** before retrying the request. This helps
prevent repeated failures and ensures compliance with Octa’s fair use policy.

## Check API Usage

You can check the summary of your API usage and current API balance anytime on Octa app:

- Login to [Octa GST](https://cloud.octagst.com)
- Go to the **API Usage** page (check the buttons on the top).
- Select a month to check the API usage summary in that month.
- Your current API balance will be displayed in the top.