Skip to content
Ideasoft
Getting Started

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:

CredentialDescription
Client IDA randomly generated string assigned to your application. Public.
Client SecretA specially generated string for your application. Must be kept secret.
Redirect URIThe 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
GET https://your-store.myideasoft.com/panel/auth
ParameterDescription
client_idThe Client ID described above
response_typeThe method used for verification. Valid value: code
stateA randomly generated value for the request (must be verified in step 3)
redirect_uriThe 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
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

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.

ParameterDescription
codeThe authorization code used to obtain a token in step 4. Valid for 30 seconds.
stateThe value given in step 1. You must verify it to protect against MITM-type attacks.
errorError code (sent only on failure)
error_descriptionError description (sent only on failure)

Successful return example:

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

Possible error values:

errorDescription
invalid_grantThe authorization method used is invalid
access_deniedThe user chose not to authorize your application

Failed return example:

Code
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.

Code
POST https://your-store.myideasoft.com/oauth/v2/token Content-Type: application/x-www-form-urlencoded
ParameterDescription
grant_typeThe verification method. Valid value: authorization_code
client_idThe Client ID
client_secretThe Client Secret
codeThe authorization code obtained in step 3
redirect_uriThe Redirect URI

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

Code
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:

JSONCode
{ "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:

errorerror_descriptionDescription
invalid_requestInvalid grant_type parameter or parameter missinggrant_type is missing or invalid
invalid_requestMissing parameter. "code" is requiredcode is missing
invalid_requestThe redirect URI parameter is requiredredirect_uri is missing
unauthorized_clientThe grant type is unauthorized for this client_idThe grant_type used is not allowed for your application
invalid_clientThe client credentials are invalidThe given client_id or client_secret is incorrect
invalid_grantCode doesn't exist or is invalid for the clientThe given code is incorrect
redirect_uri_mismatchThe redirect URI is missing or do not matchThe redirect_uri does not match
invalid_grantThe authorization code has expiredThe 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
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:

Code
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 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:

  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.

Legacy authorization

The old authorization endpoint at /admin/user/auth was removed in v8.0; only /panel/auth should be used.

Last modified on