# Authentication

The Ideasoft API uses the **OAuth2** standard for authentication. OAuth2 is an authorization system that provides limited access to account data by sending the required parameters — without sharing a username and password.

- **authorizationUrl:** `https://your-store.myideasoft.com/panel/auth`
- **tokenUrl:** `https://your-store.myideasoft.com/oauth/v2/token`
- **flow:** `authorization_code`

:::note{title="Set your store domain"}
Every request goes to **your own store's** domain: `https://<store>.myideasoft.com` or your own attached domain. The examples show the `your-store.myideasoft.com` placeholder; to try a request, click **Test** and type your domain in the dialog's URL field — it is stored in your browser and reused for all requests. The settings icon next to the endpoint URL ("Edit server variables") does the same.
:::

## Required Credentials

You need three pieces of information to authorize your application:

| Credential | Description |
|---|---|
| **Client ID** | A randomly generated string assigned to your application. Public. |
| **Client Secret** | A specially generated string for your application. Must be kept secret. |
| **Redirect URI** | The address the user is sent back to after granting permission to your application. |

:::info{title="Registration"}
All three values must be registered in the system beforehand. When you follow **Integrations → API → Add** in the admin panel, "Redirect URL" is entered by you, while "Client ID" and "Client Secret" are generated automatically by the system.
:::

## Authorization Steps

In the `authorization_code` method, the user is redirected to a dedicated page and asked to authorize your application — no username or password is required. The process runs in four steps. These steps are followed only once per application, and only the store administrator can grant the required permissions.

### 1. Redirect to the authorization page

Redirect the user to the authorization page together with the information identifying your application:

```http
GET https://your-store.myideasoft.com/panel/auth
```

| Parameter | Description |
|---|---|
| `client_id` | The Client ID described above |
| `response_type` | The method used for verification. Valid value: `code` |
| `state` | A randomly generated value for the request (must be verified in step 3) |
| `redirect_uri` | The Redirect URI described above; the user is redirected here after approval |

Scopes are not requested per call; they are fixed by the API definition created in the admin panel (Integrations → API).

Example request:

```http
GET https://your-store.myideasoft.com/panel/auth
  ?client_id=7_7d67dc7597f034d63775c1d9ae5d9ac7f5750197f
  &response_type=code
  &state=2b33fdd45jbevd6nam
  &redirect_uri=https://client.example-app.com/auth
```

### 2. Authorization consent page

The user arrives at the authorization screen in the Ideasoft admin panel, which shows your application's name and permissions. The user can approve or deny the application.

### 3. Return to the application page

The user is redirected back to your `redirect_uri`. Depending on the outcome, the `GET` parameters contain the following values; your application should use them to obtain a token or handle errors.

| Parameter | Description |
|---|---|
| `code` | The authorization code used to obtain a token in step 4. **Valid for 30 seconds.** |
| `state` | The value given in step 1. You must verify it to protect against MITM-type attacks. |
| `error` | Error code (sent only on failure) |
| `error_description` | Error description (sent only on failure) |

Successful return example:

```http
GET https://client.example-app.com/auth
  ?state=2b33fdd45jbevd6nam
  &code=Q0ODMI2OGYjMjBkN2mJmYzNkOTE4gzMGRhZDZTcykyOGQ3M2M2YTU2ZGVlMzE2MzB2MYkc5NWzE0ZWNiYjI2MA
```

Possible error values:

| error | Description |
|---|---|
| `invalid_grant` | The authorization method used is invalid |
| `access_denied` | The user chose not to authorize your application |

Failed return example:

```http
GET https://client.example-app.com/auth
  ?error=access_denied
  &error_description=The%20user%20denied%20access%20to%20your%20application
  &state=2b33fdd45jbevd6nam
```

### 4. Token request

In this step your application sends a direct server-to-server request — independent of the user — to obtain an Access Token and a Refresh Token.

```http
POST https://your-store.myideasoft.com/oauth/v2/token
Content-Type: application/x-www-form-urlencoded
```

| Parameter | Description |
|---|---|
| `grant_type` | The verification method. Valid value: `authorization_code` |
| `client_id` | The Client ID |
| `client_secret` | The Client Secret |
| `code` | The authorization code obtained in step 3 |
| `redirect_uri` | The Redirect URI |

Example request (send as a form body; the same parameters are also accepted as a query string):

```http
POST https://your-store.myideasoft.com/oauth/v2/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&client_id=7_7d67dc7597f034d63775c1d9ae5d9ac7f5750197f
&client_secret=1sowg0oogc4wg4w4o4gh4va57gggwskkgo08m44ksog8kmu88o
&code=Q0ODMI2OGYjMjBkN2mJmYzNkOTE4gzMGRhZDZTcykyOGQ3M2M2YTU2ZGVlMzE2MzB2MYkc5NWzE0ZWNiYjI2MA
&redirect_uri=https%3A//client.example-app.com%2Fauth%2F
```

A successful request returns `HTTP 200` with a JSON body like:

```json
{
  "access_token": "OGE3MzkxNDlhOGY0M2RjZWM1MWI2MWIxZjRmNDJhZThiOGJkOWZlMWIwNzVkYWFlOWFiMDAxYzkwMDlmMDhlMw",
  "expires_in": 86400,
  "token_type": "bearer",
  "scope": "The permissions you hold are shown here.",
  "refresh_token": "NjczY2E2NzZiNDJjZWI5NTE2YjZhNTlhYTJmOTQ5MjljN2MwNmUxM2MzODc5YTE4OGVjMDdlYTBiMzY1MWI1Mw"
}
```

A failed request returns `HTTP 400` with a JSON body containing `error` and `error_description`. Possible errors:

| error | error_description | Description |
|---|---|---|
| `invalid_request` | *Invalid grant_type parameter or parameter missing* | `grant_type` is missing or invalid |
| `invalid_request` | *Missing parameter. "code" is required* | `code` is missing |
| `invalid_request` | *The redirect URI parameter is required* | `redirect_uri` is missing |
| `unauthorized_client` | *The grant type is unauthorized for this client_id* | The `grant_type` used is not allowed for your application |
| `invalid_client` | *The client credentials are invalid* | The given `client_id` or `client_secret` is incorrect |
| `invalid_grant` | *Code doesn't exist or is invalid for the client* | The given `code` is incorrect |
| `redirect_uri_mismatch` | *The redirect URI is missing or do not match* | The `redirect_uri` does not match |
| `invalid_grant` | *The authorization code has expired* | The given `code` has expired |

## Token Validity

The **Access Token** you receive is used in all subsequent API calls and is valid for **24 hours**.

When the Access Token expires, a new one can be obtained with the **Refresh Token**:

```http
POST https://your-store.myideasoft.com/oauth/v2/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&client_id=7_7d67dc7597f034d63775c1d9ae5d9ac7f5750197f
&client_secret=1sowg0oogc4wg4w4o4gh4va57gggwskkgo08m44ksog8kmu88o
&refresh_token=NjczY2E2NzZiNDJjZWI5NTE2YjZhNTlhYTJmOTQ5MjljN2MwNmUxM2MzODc5YTE4OGVjMDdlYTBiMzY1MWI1Mw
```

Every Access Token request made with a Refresh Token also **rotates the Refresh Token**. If both tokens are refreshed regularly with a correct setup, no re-authorization is needed. The Refresh Token is valid for **2 months**; after that, the user must grant permission again.

## Calling the API

Send the access token in the `Authorization` header on every request:

```http
Authorization: Bearer <access_token>
```

The token's permissions are determined by the API definition created in the admin panel (no per-request scopes); see the security definition in the [Admin API](/admin-api) spec for the full scope list. For endpoint and field details, see the [OAuth reference](/oauth).

## Example authorization with Postman

The authorization steps in Postman are:

1. In the request's **Authorization** tab, select **OAuth 2.0**.
2. Set the grant type to **Authorization Code** (`authorization_code`) and the Callback URL to `https://www.getpostman.com/oauth2/callback`. The Callback URL must be defined exactly the same as the Redirect URI in the admin panel.
3. Fill in **Auth URL:** `https://your-store.myideasoft.com/panel/auth` and **Access Token URL:** `https://your-store.myideasoft.com/oauth/v2/token`.
4. Take the **Client ID** and **Client Secret** values from the API credentials you defined in the admin panel.
5. Click **Get New Access Token** to be redirected to the authorization page and sign in with the user you granted permissions to. After accepting the permissions, the Access Token becomes usable in Postman.

:::warning{title="Legacy authorization"}
The old authorization endpoint at `/admin/user/auth` was removed in v8.0; only `/panel/auth` should be used.
:::
