User Authentication

Use this guide to sign in to WEDA Console or call protected WEDA APIs with your user account. It covers session setup, API access tokens and token refresh, including the steps needed by a separate HTTP client.

User authentication has two stages:

• User session: Sign-in establishes the AdvOidc.Login cookie. This is the credential used for the Cookie-based token exchange.
• API access: The WEDA token endpoint returns an accessToken. Send it as a Bearer token when calling protected WEDA APIs.

Note: Separate API clients

WEDA Console performs its token exchange as part of the application login flow. A separate HTTP client needs its own authentication context; signing in through your browser does not populate that client's cookie jar.

For local browser application sign-in, see PKCE in this Authentication category. The steps below cover the user session and Cookie-based token exchange.

Establish a User Session

Before signing in, prepare your WEDA environment URL, tenant path and user account. Use the environment and organization access assigned to you.

In WEDA Console:

1. Open your environment's Console URL, for example https://weda.example.com/central/weda.
2. Complete the sign-in page presented by the environment.
3. Confirm that you return to WEDA Console with the intended account and tenant.

Check the result: You can open the Console after sign-in. For Console operations, continue using its UI; you do not need to manually copy its token for each action.

For a separate API client: Establish the session in that client and preserve its cookies through the SSO requests. The 0-WiseSso collection in the WEDA Postman API Collection runs these login requests before calling the WEDA token endpoint.

SSO request sequence for an HTTP client

Use the same cookie jar throughout this sequence. The examples below use {domain} for the WEDA origin and {tenantPath} for the tenant, such as central.

1. Initialize the session:

   GET {domain}/{tenantPath}/portal/external-login?returnUrl={domain}/{tenantPath}/weda

   Read the login context, including tenantId, from the redirect.

2. Submit the user's credentials to the identity service:

   POST {domain}/identity/api/v1.0/account/login
   Content-Type: application/json
   
   {
     "account": "you@example.com",
     "password": "your-password",
     "tenantId": "your-tenant-id"
   }

   Preserve the returned session cookies. The identity service path is /identity, without a tenant prefix.

3. Request the login return flow again:

   GET {domain}/{tenantPath}/portal/external-login?returnUrl={domain}/{tenantPath}/weda

   Parse the returned HTML form to obtain its action URL and the hidden code, state and iss fields.

4. Submit the form to its action URL:

   POST {form_action}
   Content-Type: application/x-www-form-urlencoded
   
   code={code}&state={state}&iss={iss}

   Preserve the AdvOidc.Login cookie returned by the completed sign-in flow.

Check the result: The HTTP client's cookie jar contains the session cookie needed by the next token request. If you implement the flow in code, preserve cookies and parse the returned form instead of hard-coding its action URL or hidden fields.

Get an API Access Token

Use the cookie-enabled client that completed the session flow. For example:

POST https://weda.example.com/central/weda/api/v1/auth/tokens

Replace the example origin and tenant with your environment. This Cookie-based request does not need a body; the client sends the session cookie established in the previous stage.

1. Confirm that the request targets the same WEDA environment and tenant used during sign-in.
2. Send the token request with the session cookie.
3. Read the returned accessToken, refreshToken, expiresIn and tokenType.

Check the result: The endpoint returns 201 Created and an access token you can use for WEDA API requests.

Example response:

{
  "accessToken": "your-access-token",
  "refreshToken": "your-refresh-token",
  "expiresIn": 7200,
  "tokenType": "Bearer"
}

expiresIn is measured in seconds. Use the value returned by your environment; the value above is an example, not a lifetime to hard-code into your client.

For the complete request and response reference, see Create JWT access token.

Use and Refresh Your Token

Call a protected API

Include the access token in the request header:

Authorization: Bearer {accessToken}

Use accessToken here. The login cookie establishes the session, while refreshToken is used to obtain a new access token.

Refresh access

Use the same token endpoint with the refresh grant:

POST https://weda.example.com/central/weda/api/v1/auth/tokens?grant_type=refresh_token
Content-Type: application/json

{
  "refreshToken": "your-refresh-token"
}

1. Send the refresh token with grant_type=refresh_token. This refresh request does not require an Authorization header.
2. Read the token response and update the values used by your client.
3. Use the returned access token for subsequent API requests.

Check the result: The token request succeeds and your client uses the returned access token. If refresh fails, establish a user session again rather than repeatedly sending the same failed request.

Caution: Protect authentication secrets

Keep passwords, session cookies, access tokens and refresh tokens out of shared examples and exported environments.

Troubleshooting

What you see	What to check
Console sign-in succeeds, but a separate API client cannot get a token	Establish the session in that client. Its cookie jar is separate from the browser's.
The token endpoint reports that no valid credentials were found	Confirm that the session flow completed and that the token request includes the matching session cookie.
The SSO request sequence does not complete	Check the environment, tenant context, preserved cookies, form action and hidden fields. Use /identity without a tenant prefix for the identity service.
A protected API rejects your request	Check the Bearer header, the returned token lifetime and whether the account has access to the requested resource.
A refresh request fails	Check grant_type=refresh_token and the submitted refresh token. If the request still fails, sign in again.