Next Steps:
Choose the authentication flow that matches your use case:

1. OAuth Access Tokens if you are building an app that
   installs into other organisations. eg you are an app designer and want to have
   your users access their Vinsight data through your app.
2. Personal Access Tokens if you are accessing
   your own organisation's data eg for external reporting or automation.

Authenticating via OAuth (authorization code grant)

Vinsight uses OAuth 2.0’s authorization code grant
flow to issue access tokens on behalf of users. The following diagram
illustrates the OAuth flow based on the actions of the user, your app, and Vinsight.

1. The user makes a request to install your app.
2. Your app redirects to Vinsight to load the OAuth grant screen and requests the
   required scopes.
3. Vinsight displays a prompt to the user to give authorization to the app, and
   prompts the user to log in if required.
4. The user consents to the scopes and is redirected to the redirect_uri with a
   unique code.
5. Your app makes an access token request to Vinsight using the client_id, client_secret, and the
   unique code.
6. Vinsight returns the access token and requested scopes.
7. Your app uses the access token to make requests to the Vinsight API.
8. Vinsight returns the requested data.

Before you begin, create an OAuth Application. The
authorization code grant flow has two additional requirements:

• A Partner Account — the install flow issues a client_id and client_secret on behalf
  of other organisations, which requires your Vinsight account to be converted to
  a Partner Account. Email support@vinsight.net to arrange this.
• At least one redirect URL registered on your OAuth Application
  (used in step 2 below).

1. Ask for permission

Before your app can access any Vinsight data, a user must grant permission to your
app. Granting permission happens when a user clicks the link to install your app.

Show the installation screen for your app

To show the installation screen for your app inside Vinsight, redirect the user to
the following URL with the query parameters defined below:

https://app.vinsight.net/oauth/authorize?client_id={client_id}&scope={scopes}&redirect_uri={redirect_uri}&state={nonce}

2. Confirm installation

When the user clicks the "Install App" button in the prompt, they're redirected to
your app's server. The authorization_code is passed
in the confirmation redirect:

https://example.com/oauth/redirect?code={authorization_code}&state={nonce}

Make sure that the state nonce returned to you is the same that you sent.

3. Get access token

Now you can exchange the authorization_code for an
access token by sending a request to Vinsight's /oauth/access_token endpoint:

POST https://app.vinsight.net/oauth/access_token

The server responds with an access token:

{
"scope": "write_salesorders,read_contacts,read_stockitems",
"access_token": "eyJ0eXAiOiJ ... 3HgH3Yxsau2UE7k",
"token_id": "gbc2l2tz25 .... e7tq",
"expires_in": 31536000
}

The following values are returned:

If the user re-authorises your application for any reason, all prior tokens for this
Vinsight Organisation will become invalid.
Make sure you are always querying with the most recent access token, otherwise you
will receive a 401 Unauthorised error.

4. Make Authenticated Requests

After your app has obtained an OAuth Access Token, it can make authenticated requests
to our API. These requests are accompanied with a header
X-Access: {access_token} where {access_token} is replaced
with the token you received in the previous step.

curl -X GET \
https://app.vinsight.net/LoginContexts/Current.json \
-H 'X-Access: {access_token}'

Authenticating via Personal Access Tokens (recommended
for your own data)

A Personal Access Token (PAT) is a scoped (you can set permissions to limit access),
revocable Bearer token that you issue directly from within your Vinsight account.
PATs are the recommended alternative to API keys when you want to
access your own organisation's data programmatically — for example from a script, a
reporting tool, or an AI agent.

Compared to API keys, Personal Access Tokens offer:

• Scoped permissions — each token grants access only to the
  resources you select, reducing the blast radius if a token is ever exposed.
• Explicit expiry — you choose the lifetime at issue time; the
  token automatically stops working after that date.
• Instant revocation — tokens can be revoked immediately from the
  OAuth Applications area without affecting other tokens or users.
• Named identity — each token carries a name and install record,
  so audit logs show which token made each request.

1. Create an OAuth Application

If you have not already, create an OAuth
Application. Personal Access Tokens do not require a
Partner Account or any redirect URLs — you only need the application itself.

You do not strictly need to save the client_secret to issue a
Personal Access Token manually. Save it only if you want to be able to
programmatically issue access tokens via the API rather than generating them by
hand. We can only show the client_secret to you once at
creation time; if you need to regenerate one, email support@vinsight.net.

2. Issue a Personal Access Token

On the OAuth Application you want to issue the token for and find the
Personal Access Tokens section.
Fill in the details:

After clicking Issue Personal Access Token, the token value is shown
once only. Copy it to a secure location — it cannot be retrieved
again.
If you lose it, revoke it and issue a new one.

3. Make Authenticated Requests

Include the token as a Bearer token in the Authorization header:

curl -X GET \
https://app.vinsight.net/SalesOrders.json \
-H 'Authorization: Bearer {access_token}'

Alternatively, use the X-Access header (same
behaviour):

Or pass the token as a query parameter using the access_token parameter (RFC 6750):

https://app.vinsight.net/SalesOrders.json?access_token={access_token}

4. Revoking a Token

To revoke a token, open the OAuth Application in the portal, find the token in the
Personal Access Tokens list, and click Delete
button.
Revocation takes effect immediately — any subsequent request using that token will
receive a 401 Unauthorized
response.

Authenticating via API key (obsolete)

NB: API keys are now obsolete and you should use a Personal Access Token instead,
which is more secure and flexible. API keys will continue to work for existing
keys but we will not issue new ones. If you need a new API key, please create a
Personal Access Token instead and update your applications to use that.

© 2012, ↑ Vinsight Documentation