Authenticates the provided credentials and creates a user session.

Required Permission(s)

All of the following:

• A user group to which the user belongs must be granted access to the API key given in authorization header
• Must be running script from a valid source address as configured in API registration for the given API key

Authorization header

• key - the API key configured in BeyondInsight for your application
• runas - the username of the BeyondInsight user to authenticate as
• pwd - the RunAs user password, enclosed in square brackets and followed by a semicolon. Required only when the User Password factor is enabled on the API registration. If the brackets or the trailing semicolon are omitted the password is read as empty and the request fails with 401
• token - a Personal Access Token. Required only when the Personal Access Token factor is enabled on the API registration. Unlike pwd, it needs no brackets and no trailing semicolon. Tokens are created for a user in the BeyondInsight console; there is no Public API endpoint for creating one
• challenge - the answer to a two-factor challenge. See the two-factor note below
• Parameter names are not case sensitive. Semicolons separate parameters, so a value may not contain one - except pwd, which is read as everything between its square brackets and so may contain semicolons
• Example: Authorization=PS-Auth key=c479a66f...c9484d; runas=doe-main\johndoe; pwd=[un1qu3];

Session state

• A successful sign-in returns a session cookie. Your HTTP client must store it and send it on every subsequent request
• The session expires after 20 minutes of inactivity
• Call POST Auth/Signout when you are finished with the session

Two-factor challenge

• When a two-factor challenge is configured, two calls to this endpoint are required and the session must be maintained between them
• The first call returns 401 with a WWW-Authenticate-2FA header containing the prompt from the authentication service
• Call the endpoint again with the answer supplied as the challenge parameter in the authorization header
• If the WWW-Authenticate-2FA header is absent, no two-factor challenge is configured for the user

Causes of a 401

• An invalid API key, or a RunAs user that is unknown or not permitted to use the key
• A required authentication factor is missing or invalid - user password, Personal Access Token, two-factor, source address, or X-Forwarded-For
• The user session has expired
• The API key has been rotated but not updated in the calling script
• Authentication rule failures all return the same generic body. The specific reason is not in the response; it is recorded in a BeyondInsight User Audit entry - look there first
• The product is not licensed. This is not an authentication rule failure: the body reads Product is not licensed. and nothing is written to the audit trail
• Repeated failures of the user password, Personal Access Token or two-factor factors count towards the account lockout threshold and will lock the RunAs user. An invalid API key does not count towards it. A successful sign-in resets the counter

Additional requirements for Pathfinder users

• Supported user types: Application, Local, Active Directory, Microsoft Entra ID, and LDAP
• Local Users must first be scaffolded from Pathfinder, and Directory Users must first be provisioned by platform SSO or SCIM; neither is created on demand
• No directory password is verified on this path; the API key and RunAs user identify the caller
• Expected response on Condition Failure: 401 Unauthorized

OAuth with Bearer token

• To use OAuth sign-in, request an access_token using "Password Safe OAuth Proxy" API
• Set the following header: Authorization: Bearer [access_token]
• Calling this endpoint is optional when using a bearer token - a bearer token authenticates each request on its own. Call it only if you also want a session cookie
• To impersonate another user, supply their username in a separate RunAs header. This is not the same as the runas parameter inside the PS-Auth authorization value. You may only impersonate users who share a group with the application user