Request just-in-time administrator access to a computer

GET 
/computers/:computerId/access

deprecated

This endpoint has been deprecated and may be replaced or removed in future versions of the API.

Deprecated: use POST /computers/{computerId}/access instead; it takes the same parameters in the request body.

Creates a JITA access request that adds the caller (or, for an admin, another user) to the local administrators of the computer. The request is queued for a worker; for a request made for yourself, poll GET /queue/pending/{systemId} to follow it. Until a worker picks it up, the request stays pending.

Parameters are read from the query string on GET and from the request body on POST (JSON or urlencoded). The POST form is functionally identical, and a POST with no body at all is accepted (all defaults). t sent as a numeric string in a JSON body ("30") is accepted.

Who can call it

• Any authenticated role (superadmin, admin, user) may request access for themselves, provided they are a system administrator of the computer: a direct entry in the computer's admin inventory, or a member of a group in it (the request then records accessViaGroup). Otherwise the response is 403.
• The built-in secureone account is not a directory user, so it gets 422 User not found here. A superadmin token that belongs to a real directory user works for self requests like any other role.
• Requesting on behalf of another user (userId differs from the caller) requires the caller's role to be exactly admin. user and superadmin tokens get 403 (checked before the target is looked up). A userId equal to the caller's own id is a self request. For an admin caller, a malformed userId is 422 Invalid User ID: "<value>", an unknown one 422 User not found, and a user who is not a system administrator of the computer 422 The target user with ID '<id>' is not a system administrator.

Duration (t): a positive number of minutes. The default and maximum come from server feature settings (both 240 when unset). A value above the maximum, a negative value, or a non-integer number (for example 1.5) returns 400 InvalidQuery 'Invalid Access Duration Requested.'. A value that is absent, empty, 0, or not numeric (abc) is silently replaced with the default (this differs from the extend endpoint, which also defaults values above the maximum).

Conflicts (409): Access has already been requested to this computer. while the earlier request is pending, and Access has already been granted to this computer. once it is active. Both carry context.id and context.expires.

Linux and macOS: for macOS computers and Linux computers using Netwrix directory bridging, the access token must carry the caller's encoded password (encpass); otherwise 409 Missing encpass in token for access request. On-behalf requests are not supported for those systems (422 JITA requests on behalf of another user are not supported for Mac systems and Linux systems using Netwrix directory bridging.). A Linux computer whose bridging strategy is not secureone has neither restriction. PUT and DELETE return 405 with an empty body.

Required role: any authenticated user (on-behalf requests need admin).

Request

Responses

200

Access request queued.

400

Bad request. Access routes: InvalidQuery 'Invalid Access Duration Requested.' for a bad t. Any route: InvalidQuery 'illegal key "$ne" in query|body' when a query or body key starts with $. Malformed JSON gives an untyped {error} body. Sudoers routes: BadRequestError for a non-Linux computer, a missing or empty sudoers_blob, or a missing sudoersHash. Admin add/remove on Linux: BadRequestError carrying the sudoers service message. Missing or malformed ids on the admin routes are 422, not 400.

401

No token, or the token is invalid or expired. The body is {message}: No auth token provided when no token is sent, otherwise the token check's message (jwt expired, jwt malformed, invalid signature, invalid token, jwt signature is required). Send Authorization: Bearer <token> exactly: the server drops the first seven characters of the header and reads the rest as the token, so a different scheme or an extra space fails. If Authorization is absent, the server reads a token field in the body, then a token query parameter, then x-access-token. Routes that validate query fields reject ?token= with 400 InvalidQuery.

403

The token's role is not allowed for this operation, or the token's scopes exclude the route (Scope not allowed by token).

404

No record has the :id in the path (the id is malformed or unknown). The body is the bare text Invalid <Type> ID (for example Invalid Computer ID, Invalid User ID) with Content-Type text/html; charset=utf-8, not JSON. Some routes return an empty body.

409

Access is already requested (Access has already been requested to this computer.) or already granted (Access has already been granted to this computer.); context holds the existing request id and expires. Also returned, without context, when the token lacks the caller's encoded password for a macOS or directory-bridged Linux computer (Missing encpass in token for access request.).

422

Unprocessable: User not found (unknown caller or userId, including the built-in secureone account), Invalid User ID: "<value>" (malformed userId), the target user is not a system administrator of the computer, or an on-behalf request for a Mac or Netwrix-bridged Linux computer.