Skip to content

Authentication

Environments

We provide two separate environments for API access:

Staging Environment

  • Portal: https://portal.stag.vml.visma.ai/
  • Use for: Development, testing, and automated integration tests
  • Data: Test data only - no real customer information
  • Projects: Completely separate from production

Production Environment

Important

Projects created in staging and production are not linked. You must set up separate projects in each environment. Test thoroughly in staging before moving to production.

Getting Started with Authentication

All API requests require authentication using bearer tokens. You generate these tokens from your project's portal, then include them in the Authorization header of your API requests.

Server to server token

Authentication is done using a bearer token, set it in the Authorization header as follows: 

Authorization: Bearer Token

You can use an API token for server to server communication, and you can issue a valet key for use by mobile/web clients.

Note

Please do not put your api token into an untrusted client like a mobile application!

Demo token

For quick testing against staging you can use the shared demo token instead of a project token. The demo token is rate-limited, shared by everyone, and scoped to prediction endpoints only:

  • Smartscan (sync) — POST /v1/document:annotate
  • Smartscan Async — POST /v1/transactions (create) and the GET /v1/transactions/... status and results endpoints

Every other operation — feedback submission (Smartscan, async result updates, and Product Types feedback), transaction and tag deletion, valet key issuance, and all Autosuggest, dataset, model and Product Types requests — is not available with the demo token and returns PERMISSION_DENIED. Generate a project token from the portal for those.

Warning

Do not send sensitive data with the demo token — anyone holding it can read the data.

Valet Key - shortlived token

For a mobile/web application, you have two options:

  • Call our Access API from your backend with server to server token to issue a shortlived token that the application can use to talk to Smartscan on your behalf.
  • If you have an OpenID Connect based identity provider (e.g Visma Connect), you can reuse existing authentication.

Reusing existing authentication for mobile will be beneficial both for performance and you can avoid having to do backend work. The flow used on mobile is called "PKCE for OAuth2.0" (RFC7636). We support both Access Tokens and Identity Tokens, for ease of use and quick on-boarding. Please note that this technique is not limited to Visma Connect, any OAuth / OpenID Connect provider that exposes a JSON Web Key Endpoint can be used.

Contact us on support if you would like to implement this flow.

Valet Key Request

You provide a sub(ject) and get back a token. The subject is optional, but highly recommended.

Shortlived tokens are limited to prediction, feedback submission, async transaction endpoints, and read-only training status and usage metrics; creating, modifying or deleting datasets, models and data is disabled.

You will get back an ID and a Token which can be used as bearer token. The ID is not currently used, but we plan to support revoking tokens by ID.

You can set a custom expiration date by providing an unix timestamp in the field "exp", but it has to be less than 48 hours in the future. We only support shortlived tokens for the valet key flow. The default expiry is 8 hours.

Request

POST v1/access/valetkey

https://api.stag.ssn.visma.ai/v1/access/valetkey

Authorization - Bearer Token

Token: [API token]

Body - raw (json)

Body 
{
    "sub":"1234"
}

Response

200 OK POST v1/access/valetkey

https://api.stag.ssn.visma.ai/v1/access/valetkey

Body - raw (json)

Body 
{
    "id": "babd92f9-6f49-44ec-a8fb-5480feb39664",
    "token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJjbGllbnRfaWQiOiJ2bWwiLCJleHAiOjE3MjYxNzI3NzQsImlhdCI6MTcyNjE0Mzk3NCwiaXNzIjoic21hcnRzY2FuIiwianRpIjoiYmFiZDkyZjktNmY0OS00NGVjLWE4ZmItNTQ4MGZlYjM5NjY0Iiwic3ViIjoiMTIzNCJ9.WnT8pv7RtIhP0lZGab3o65FSF2GXuL9bh-jQ6YdnRZnRRtlxTYiaLnt8L1nd3b0b09iSaNx9SnjngzPD2UEd4A"
}