Skip to main content

Obtain an Access Token

Goal​

Obtain an OAuth2 access token from the Parsware Identity Service so you can call platform APIs while developing.

Prerequisites​

  • The Identity Service is running and reachable (in local development it listens on http://localhost:5000).
  • The development seed data has been created (it is created automatically on first startup): a dev tenant and an administrator account (admin@parsware.local).
  • A REST client such as curl.

Steps​

  1. Request a token from the token endpoint using the development client and the seeded administrator's credentials:

    curl -X POST http://localhost:5000/connect/token \
      -H "Content-Type: application/x-www-form-urlencoded" \
      -d "grant_type=password" \
      -d "username=admin@parsware.local" \
      -d "password=Passw0rd!" \
      -d "scope=profile roles parsware.api offline_access" \
      -d "client_id=parsware-dev-cli" \
      -d "client_secret=dev-cli-secret"

  2. Read the access_token from the JSON response. The response also includes a refresh_token (because offline_access was requested) and an expires_in value in seconds.

  3. Call an API with the token in the Authorization header. To confirm the token works, call the userinfo endpoint:

    curl http://localhost:5000/connect/userinfo \
      -H "Authorization: Bearer <access_token>"

    The response identifies the signed-in user (subject, name, email, tenant).

What happens behind the scenes​

The Identity Service verifies the administrator's password, then issues a signed JWT access token. The token is signed (not encrypted), so any platform service validates it directly using the Identity Service's published signing keys — there is no callback to the Identity Service on every request.

Troubleshooting​

  • invalid_grant — the username or password is wrong, or the account is locked out after repeated failures. Wait and retry, or reset the password.
  • invalid_client — the client_id/client_secret do not match a registered client. In development, use parsware-dev-cli / dev-cli-secret.
  • invalid_scope — a requested scope is not permitted for the client. Request only profile, roles, offline_access, and parsware.api.
  • Connection refused — the Identity Service is not running or is on a different port.
  • The token only carries mfa.enrol (its aud is parsware-mfa-enrolment) — the account is a staff account with no authenticator app yet. Staff MFA is mandatory: enrol one (from the profile, or POST /connect/mfa/enrolment with this token), then request again with -d "mfa_code=<the six digits>". On a deployment the administrator is whoever the deployment's PLATFORM_ADMIN_EMAIL names, not admin@parsware.local.
  • Inspect the JWKS keys the Identity Service publishes.

The password grant shown here is a development convenience for obtaining a token from the command line. Real interactive sign-in uses the authorization code flow with PKCE through the Platform Shell.