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
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. |
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:
Code
| 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:
Code
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:
Code
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:
Code
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.
Code
| 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):
Code
A successful request returns HTTP 200 with a JSON body like:
Code
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:
Code
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:
Code
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 spec for the full scope list. For endpoint and field details, see the OAuth reference.
Example authorization with Postman
The authorization steps in Postman are:
- In the request's Authorization tab, select OAuth 2.0.
- Set the grant type to Authorization Code (
authorization_code) and the Callback URL tohttps://www.getpostman.com/oauth2/callback. The Callback URL must be defined exactly the same as the Redirect URI in the admin panel. - Fill in Auth URL:
https://your-store.myideasoft.com/panel/authand Access Token URL:https://your-store.myideasoft.com/oauth/v2/token. - Take the Client ID and Client Secret values from the API credentials you defined in the admin panel.
- 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.
Legacy authorization
The old authorization endpoint at /admin/user/auth was removed in v8.0; only /panel/auth should be used.