REST API Authentication in OutSystems: OAuth2, Bearer Tokens, and API Keys

Before writing any authentication logic, create secure storage for your credentials. O11: Go to Data tab → Site Properties → right-click → Add Site Property. Create: - ApiBaseUrl (Text) — the external API base URL - ApiClientId (Text) — OAuth2 client ID - ApiClientSecret (Text) — OAuth2 client secret (mark as Secret: Yes) - ApiKey (Text) — static API key (mark as Secret: Yes) Set default values and configure per-environment values in Service Center → Factory → [Module] → Site Properties. ODC: In ODC Portal, navigate to your App → Settings → Secret Settings. Create the same keys. Secret Settings are encrypted at rest and never visible after saving. Access them in action flows via the GetSetting system action.

Open your consumed REST API node under Logic tab → Integrations → REST. In the Properties panel, find the On Before Request property. If the external API uses Basic Auth (username:password encoded in the Authorization header), you have two options: Option A — Method-level header (simple): In the REST method dialog, Headers/Auth tab → Add Header → Name: Authorization, Value: "Basic " + ToBase64(Username + ":" + Password). This is static — only use for dev/test. Option B — OnBeforeRequest callback (recommended for production): Set the On Before Request property to New OnBeforeRequest. Inside the callback action: Start → GetSiteProperty (ApiUsername) → GetSiteProperty (ApiPassword) → Assign (Request.Headers append Authorization = "Basic " + ToBase64(ApiUsername + ":" + ApiPassword)) → Assign CustomizedRequest = Request → End

For APIs using OAuth2 machine-to-machine (client credentials flow): O11 built-in support: 1. Click your consumed REST API node in Logic tab → Integrations → REST 2. In Properties panel, set Authentication to OAuth 2.0 3. Fill in: Authorization Server URL (the token endpoint), Client Id, Client Secret, Scopes 4. Service Studio handles token fetching and refresh automatically Advanced pattern (works in both O11 and ODC — use when built-in doesn't support your IdP's token format): 1. Create a Server Action FetchOAuthToken 2. Inside, call a REST method POST to the token endpoint with body: grant_type=client_credentials&client_id={Id}&client_secret={Secret}&scope={Scopes} 3. Parse the access_token from the JSON response 4. Store the token in a Site Property or cache entity with ExpiresAt timestamp 5. In OnBeforeRequest: fetch the cached token, check if expired → refresh if needed → inject into Authorization header Action flow for OnBeforeRequest: Start → GetCachedToken → If (Token.ExpiresAt < CurrDateTime()) → [True] FetchOAuthToken → UpdateCachedToken → [False] (proceed) → Assign (Request.Headers append Authorization = "Bearer " + Token.AccessToken) → Assign CustomizedRequest = Request → End

To protect your exposed REST API with an API key: 1. Click your exposed REST API node (Logic tab → Integrations → REST → your API) 2. In Properties panel, set Authentication to Custom 3. An OnAuthentication action is automatically added under your REST API node Open the OnAuthentication action and build this flow: Start → GetRequestHeader (Name = "X-API-Key") → GetApiKeyRecord [Aggregate: ApiKey entity, Filter: ApiKey.KeyValue = GetRequestHeader.Value AND ApiKey.IsActive = True AND ApiKey.ExpiresOn > CurrDateTime()] → If (GetApiKeyRecord.List.Empty) → [True] Raise Exception (InvalidApiKey User Exception) → [False] End The raised InvalidApiKey User Exception automatically causes OutSystems to return HTTP 403 Forbidden to the caller. No additional response-writing is needed.

For token-based authentication on your exposed API: 1. Set Authentication to Custom on the exposed REST API node (same as step 4) 2. Open the OnAuthentication action Action flow: Start → GetRequestHeader (Name = "Authorization") → Assign (BearerToken = Replace(AuthHeader, "Bearer ", "")) → ValidateToken [Server Action or Aggregate that verifies the token against your token store or calls an OIDC introspection endpoint] → If (IsTokenValid = False) → [True] Raise Exception (UnauthorizedAccess Security Exception) → [False] Assign (CurrentUserId = TokenPayload.UserId) → End For JWT tokens, use the JWT Forge component (Logic tab → Manage Dependencies → search JWT). The ValidateJWT action verifies the signature and expiry. Extract claims (sub, roles, exp) from the validated token. TrueChange note: Raising a Security Exception from OnAuthentication causes OutSystems to return HTTP 401 Unauthorized — appropriate for token validation failures.

After publishing (Ctrl+F5), test both positive and negative cases: Using the Swagger UI (right-click exposed REST API → Open Documentation): 1. Click Authorize in the Swagger UI 2. Enter your API key or Bearer token 3. Execute a method — verify 200 response 4. Remove or corrupt the credential — verify 401 or 403 response For consumed APIs, add a Test Server Action that calls your imported method and trace the execution in the Service Studio Debugger: 1. Set a breakpoint on the Aggregate or GetProperty node 2. Press Debug (F6) 3. Step through to verify the Authorization header is correctly set in the OnBeforeRequest output Check Service Center → Monitoring → Integrations for logs of outgoing REST calls including request headers and response status codes.