Skip to content

Martini Identity Functions

Overview

Martini Identity Functions let your services and workflows check whether an incoming HttpServletRequest is authenticated or authorized, outside the automatic enforcement that Martini already applies to REST APIs. This is useful when you need to verify a caller's identity manually, for example inside an HTTP Filter trigger or a custom Groovy endpoint that is not covered by REST API scopes.

What You Will Learn

  • How to check whether a request is authenticated with IdentityMethods.isAuthenticated
  • How to check whether a request is authorized for specific scopes with IdentityMethods.isAuthorized
  • How the throwException/throwIfUnauthorized parameters change the return value and exception behavior of each function
  • How isAuthorized scope names relate to the scopes you configure on a REST API

When To Use This

Use Martini Identity Functions when you need to:

  • Verify authentication inside an HTTP Filter trigger, before Martini's REST API scope enforcement has a chance to run
  • Guard a custom Groovy endpoint or non-REST-API workflow path with the same scope names you already use for REST API scopes
  • Resolve or confirm the current user for a request without relying on REST API-level scope configuration

Prerequisites

Checking Authentication with isAuthenticated

isAuthenticated checks whether the current HttpServletRequest is authenticated.

Parameters

Property Type Required Description
request HttpServletRequest Yes The request to check for authentication. Must not be null.
throwException Boolean No Whether to throw a RequestUnauthenticatedException instead of returning false when the request is not authenticated. Defaults to false.

Return Value and Exceptions

Returns true if the request is authenticated and false if it is not, provided throwException is false (the default). When throwException is true, a RequestUnauthenticatedException is thrown instead of returning false for an unauthenticated request.

1
2
3
4
boolean authenticated = IdentityMethods.isAuthenticated($__request, false)
if (!authenticated) {
    // Handle the unauthenticated request, e.g. reject it.
}

Expected result: authenticated is true when the request carries valid credentials resolvable by the configured identity provider, and false otherwise.

Migrated from HttpMethods

IdentityMethods.isAuthenticated replaces the deprecated HttpMethods.authenticated, using the same request and throwException parameters. See Migrating from Deprecated HttpMethods Functions for the full migration table and backward-compatibility notes.

Checking Authorization with isAuthorized

isAuthorized is a new function introduced in Martini Runtime v2.8.0. It determines whether the current HttpServletRequest is authorized to access a resource guarded by one or more scopes — the same scopes you configure for REST API scopes, but checked manually for use cases that REST API scope enforcement does not cover, such as an HTTP Filter trigger.

1
public static boolean isAuthorized(HttpServletRequest request, List<String> scopes, boolean throwIfUnauthorized)

Parameters

Property Type Required Description
request HttpServletRequest Yes The incoming request used to verify authentication status. Must not be null.
scopes List<String> Yes The required scope values, without the org prefix (for example, "admin", "manager"), matching the scope names used in REST API scopes. Must not be null. If empty, only authentication is checked.
throwIfUnauthorized Boolean No Whether to throw an exception instead of returning false when authorization fails. Defaults to false.

Scope Matching Semantics

isAuthorized resolves the current user from the given request using the configured identity provider's current-user resolution, then checks whether all of the provided scopes are present among that user's scopes/groups:

  • Returns true only if every scope in scopes is present for the resolved user.
  • Returns false if one or more scopes are missing.
  • Returns false if no user can be resolved from the given request — for example, an unauthenticated request.

Return Value and Exceptions

When throwIfUnauthorized is false (the default), isAuthorized returns false if the user is not authenticated, cannot be resolved, or lacks one or more required scopes — it never throws in these cases.

When throwIfUnauthorized is true, isAuthorized throws instead of returning false:

  • RequestUnauthenticatedException — if the user is not authenticated or cannot be resolved from the request.
  • RequestUnauthorizedException — if the user is authenticated but does not have all the required scopes.
1
boolean authorized = IdentityMethods.isAuthorized($__request, ['admin', 'manager'], true)

Expected result: authorized is true only when the resolved user has both the admin and manager scopes; otherwise the call throws RequestUnauthenticatedException or RequestUnauthorizedException as described above.

See REST API Scopes for how to define and assign the scope names you pass to isAuthorized, and Martini Services Authentication & Authorization for more on securing services and APIs.

Helpful Resources