# OpenID Connect (OIDC) and How to Authenticate with Our API

## What is OpenID Connect (OIDC)?

OpenID Connect (OIDC) is an identity layer built on top of OAuth 2.0. It allows clients (such as applications or APIs)
to verify the identity of users or services securely. OIDC provides authentication (who you are), while OAuth 2.0 mainly
handles authorization (what you can do).

In simpler terms, OIDC allows our API to confirm **who is making the request** and **what permissions they have** before
granting access.

## How to Get an Access Token Using Service Account Credentials

For machine-to-machine (M2M) authentication, we use **service accounts**. A service account is a non-human identity
that can authenticate and interact with our API.

### Prerequisites

You will receive the following credentials from us:

- `client_id` : your personal service account id
- `client_secret`: your personal service account secret
- `token_endpoint`:the URL to request the access token
- `refresh_token_endpoint`:  the URL to refresh your access token


### Requesting an Access Token

You need to make a **POST request** to our OIDC token endpoint using the **client credentials flow**.

Here’s an example using `curl`:


```bash
curl -X POST "https://{{KORUS_AUTH_URL}}/realms/korusticket/protocol/openid-connect/token" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=client_credentials" \
     -d "client_id=your-client-id" \
     -d "client_secret=your-client-secret"
```

If the request is successful, the JSON response is like this:


```json
{
  "access_token": "your-access-token",
  "expires_in": 1800,
  "refresh_expires_in": 1800,
  "refresh_token": "your-refresh-token",
  "token_type": "Bearer"
}
```

`expires_in` and `refresh_expires_id` are in seconds.

### Using the Access Token

Once you obtain the `access_token`, include it in the `Authorization` header of your API requests:


```bash
curl -X GET "https://{{KORUS_URL}}/v1/ticketing/catalogs/" \
     -H "Authorization: Bearer your-access-token"
```

### Refreshing an Access Token

You need to make a **POST request** to our OIDC token endpoint using the **client credentials flow**.

Here’s an example using `curl`:


```bash
curl -X POST "https://{{KORUS_AUTH_URL}}/realms/korusticket/protocol/openid-connect/token" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=refresh_token" \
     -d "refresh_token=your-refresh-token" \
     -d "client_id=your-client-id" \
     -d "client_secret=your-client-secret"
```

If the request is successful, the JSON response is like this:


```json
{
  "access_token": "your-access-token",
  "expires_in": 1800,
  "refresh_expires_in": 1800,
  "refresh_token": "your-refresh-token",
  "token_type": "Bearer"
}
```