Guides
  1. Quick Start

Getting an API Access

Every request to the Worklio API needs a bearer access token. To get one you need a developer account, your client credentials(credentials are shared in sandbox), and a token request against Worklio's OAuth token endpoint. This guide walks through all three.

1. Create a developer account

Register at https://apiweb.worklio.com/RegisterDeveloper.

2. Access your sandbox environment

Once you've registered, sign in to the sandbox dashboard at https://apiweb.worklio.com/Dashboard. This dashboard lists the companies attached to your developer account — it's empty until you create one, which is covered later in the guide (see the Create Company step).

3. Get an access token

Worklio's token endpoint is:

POST https://api.worklio.com/connect/token

Resource Owner Password flow

This flow exchanges a developer's own username and password, together with a client ID and secret, directly for an access token. Use it when your application is calling the API on behalf of the same account that registered it (for example, scripts, internal tools, or sandbox testing) — not for authenticating your app's end users.

ParameterTypeRequiredDescription
grant_typestringYesMust be password.
usernamestringYesYour Worklio developer account username.
passwordstringYesYour Worklio developer account password.
scopestringYesMust be api.
client_idstringYeswep_resourceowner.public.api
client_secretstringYesSandbox client secret shown below. This is a shared sandbox credential, not a per-account secret — safe to use as-is when testing against the sandbox.

The request body is application/x-www-form-urlencoded.

Example Requests

require("dotenv").config();

const USERNAME = process.env.WORKLIO_USERNAME;
const PASSWORD = process.env.WORKLIO_PASSWORD; 
const CLIENT_ID = "wep_resourceowner.public.api";
const CLIENT_SECRET = "EFFFC78854F64A17B6ADA7EA385D3C83";
const url = "https://api.worklio.com/connect/token";

async function getToken() {
  const body = new URLSearchParams({
    grant_type: "password",
    username: USERNAME,
    password: PASSWORD,
    scope: "api",
    client_id: CLIENT_ID,
    client_secret: CLIENT_SECRET,
  });

  const response = await fetch(url, {
    method: "POST",
    headers: {
      accept: "application/json",
      "content-type": "application/x-www-form-urlencoded",
    },
    body,
  });

  console.log(response.status);

  const raw = await response.text();
  console.log(JSON.stringify(JSON.parse(raw), null, 2));
}

getToken();
curl -s -X POST "https://api.worklio.com/connect/token" \
  -H "accept: application/json" \
  -H "content-type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=password" \
  --data-urlencode "username=$WORKLIO_USERNAME" \
  --data-urlencode "password=$WORKLIO_PASSWORD" \
  --data-urlencode "scope=api" \
  --data-urlencode "client_id=wep_resourceowner.public.api" \
  --data-urlencode "client_secret=EFFFC78854F64A17B6ADA7EA385D3C83" | jq .
import os
import json

import requests
from dotenv import load_dotenv

load_dotenv()

USERNAME = os.environ.get("WORKLIO_USERNAME")
PASSWORD = os.environ.get("WORKLIO_PASSWORD")
CLIENT_ID = "wep_resourceowner.public.api"
CLIENT_SECRET = "EFFFC78854F64A17B6ADA7EA385D3C83"
URL = "https://api.worklio.com/connect/token"


def get_token():
    data = {
        "grant_type": "password",
        "username": USERNAME,
        "password": PASSWORD,
        "scope": "api",
        "client_id": CLIENT_ID,
        "client_secret": CLIENT_SECRET,
    }

    response = requests.post(
        URL,
        headers={
            "accept": "application/json",
            "content-type": "application/x-www-form-urlencoded",
        },
        data=data,
    )

    print(response.status_code)

    raw = response.text
    print(json.dumps(json.loads(raw), indent=2))

    return response


if __name__ == "__main__":
    get_token()
🚧

EFFFC78854F64A17B6ADA7EA385D3C83 is a shared sandbox client_secret. It's safe to use for testing — swap in your own credentials when you move past the sandbox.


Example response

{
  "access_token": "YOUR_API_KEY",
  "expires_in": 86400,
  "token_type": "Bearer",
  "scope": "api"
}
{
  "error": "invalid_grant",
  "error_description": "invalid_username_or_password"
}
{
  "error": "invalid_client"
}

Please safely save the access_token for later use. Access tokens expire after 24 hours so you will need to get a new one each day.

Browser flow (SDK)

Resource Owner Password authenticates as the developer account itself. For applications where an end user signs in through the browser, Worklio provides an OpenID Connect client via the @worklio/sdk package instead. This flow redirects the user to Worklio's login page and returns tokens to your app — no username/password ever touches your code.

@worklio/sdk isn't published publicly — contact Worklio support to request access to it.

Configure the client

import { WepAuthFlow, WepOpenIDConnect } from '@worklio/sdk';

const CONFIG = {
  authority: 'https://api.worklio.com',
  client_id: 'wep.public.api',
  response_type: 'id_token token',
  scope: 'openid api',
  method: 'redirect',
  redirect_path: '/auth/signinwin/main',
  post_logout_redirect_path: '/auth/signoutwin/main',
  silent_redirect_uri_path: '/auth/signinsilent/main',
} as const;

const wepAuth = new WepAuthFlow({
  oidc: new WepOpenIDConnect(CONFIG),
});
ParameterTypeRequiredDescription
authoritystringYesWorklio's OIDC provider. Always https://api.worklio.com.
client_idstringYesPublic client ID for SDK-based browser apps: wep.public.api.
response_typestringYesMust be id_token token.
scopestringYesMust be openid api.
methodstringYesMust be redirect. The SDK sends the browser to Worklio's login page rather than opening a popup.
redirect_pathstringYesPath in your app the browser is sent back to once login completes.
post_logout_redirect_pathstringYesPath in your app the browser is sent back to once logout completes.
silent_redirect_uri_pathstringYesPath the SDK uses internally to renew a token without a full redirect.

Log in and get a token

// Kick off login — redirects the browser to Worklio's login page.
document.getElementById('login')!.addEventListener('click', () => {
  wepAuth.login();
});

// After the browser is redirected back to redirect_path, the SDK needs
// to resolve that callback before isLogged reflects the new session.
if (wepAuth.isCallbackResolved) {
  // handle post-redirect state here
} else if (wepAuth.isLogged) {
  const token = await wepAuth.getTokenSilently();
}

// Get (or silently renew) the current token on demand.
const token = await wepAuth.getToken();

// Log out — redirects the browser to Worklio, then to post_logout_redirect_path.
wepAuth.logout();

getToken() and getTokenSilently() resolve to the bearer token string itself, not a JSON envelope. Use it the same way as a Resource Owner Password token: Authorization: Bearer {token} on every subsequent API request — see, for example, Get Companies.

If login or token retrieval fails, getToken()/login() reject with an error rather than returning a token.

Updated 25 minutes ago

Did this page help you?