Authenticating with the Outpost REST API

Outpost API endpoints require only the JWT, others require the Admin token and some require both. A user logged in only as a BMC Discovery Outpost administrator cannot access any credentials in the BMC Discovery Outpost.

To register an unregistered BMC Discovery Outpost with a BMC Discovery instance

Using the BMC Discovery Outpost API to register the first BMC Discovery  instance with an Outpost requires only the Admin token. Because no BMC Discovery instance is yet registered, there is no JWT token that would apply.

1. Authenticate with the Outpost:
   GET the admin token from the /admin/authentication endpoint; this allows a password login and returns a token.
2. Retrieve the Outpost's registration token (using the admin token as authentication in the Authorization header):
   GET the Outpost registration token from the /admin/outpost_token  endpoint. 
3. Use the Outpost registration token to register with the instance API:
   POST the Outpost token to the instance /discovery/outposts  endpoint.
4. Get an instance registration token:
   GET the token from the instance /discovery/instance  endpoint.
5. Use the instance registration token to register with the Outpost API:
   POST the instance token to the Outpost /admin/instances  endpoint, using the admin token as authorization.

To register an Outpost with an additional instance

Using the BMC Discovery Outpost API to connect to a subsequent instance requires both (JWT and Admin) tokens. The JWT that you supply must be for a user that has permissions in the BMC Discovery instance to read credentials. This is because any second (or subsequent) instance registered will be able to use the credentials registered in the vault by the existing BMC Discovery instance or instances.

1. Authenticate with the Outpost:
   GET the admin token from the /admin/authentication endpoint that allows a password login and returns a token or use the existing one (from the procedure above).
2. Get a JWT token from the already authenticated BMC Discovery instance from BMC Helix Portal. See Access-and-authentication-for-the-REST-API in the BMC Helix Portal documentation for more information.
3. Construct the Outpost Bearer token using the following format:
   Bearer <JWT token>:<Outpost admin token>See To use the bearer tokens with the Outpost API for more information on the token.
4. Retrieve the Outpost's registration token (using the admin token as authentication in the Authorization header):
   GET the Outpost registration token from the /admin/outpost_token  endpoint. 
5. Use the Outpost registration token to register with the new instance API:
   POST the Outpost Bearer token to the instance /discovery/outposts  endpoint.
6. Get an instance registration token from the new instance:
   GET the token from the instance /discovery/instance  endpoint.
7. Use the new instance registration token to register with the Outpost API:
   POST the new instance token to the Outpost /admin/instances  endpoint.

To use the bearer tokens with the Outpost API 

The Outpost bearer token has the following format:

The three parts of this token are:

• JWT token  — The JWT obtained from BMC Helix Portal.
• A colon (':')
• admin token — issued by the Outpost admin/authentication endpoint as described above.

The JWT key and Outpost admin token, are optional. The API call is only authenticated by the token or tokens that you supply.

• To supply just a JWT key, use <JWT key>:
  The trailing ':' is optional for compatibility with any existing code that used only JWTs.
• To supply just an Admin token, use :<admin_token>
  With the leading ':' — This is the equivalent of accessing the Outpost's URL directly, and only logging in as the admin user.
• To supply both, use the full jwt:admin format. This is the equivalent of clicking through to the Outpost UI from a registered instance, and then adding Admin permissions.