REST API usage - Platform - BlueCat Gateway - 24.3.3

Gateway Administration Guide

ft:locale
en-US
Product name
BlueCat Gateway
Version
24.3.3

Users can use the POST /rest_login API endpoint to log in to either BlueCat Address Manager or Micetro.

REST API users must login through the rest_login endpoint in order to obtain their session token:

<bluecat_gateway_address>/rest_login

Users must include the username and password of their account in the login request in JSON format:

{
    "username" : "exampleUser",
    "password" : "examplePassword"
}

If the user sends only the username and password when accessing the /rest_login endpoint, BlueCat Gateway connects to the default BAM or Micetro address.

  • You can set the default BAM address in the config.py file in the api_url variable setting. If the api_url setting contains a list of addresses, then by default, Gateway connects to the first address in the list.

  • You can set a default Micetro address in the config.json file under the micetro key.

Tip: If you're passing in a BAM or Micetro URL within the request, make sure that that Gateway is configured with that URL. Otherwise, the API will return an error in response.

The call to rest_login returns the session token in the following JSON format:

{
    "access_token": "<token>"
}

Users must extract the <token> from the JSON response and insert it in the header of all subsequent requests, using the following format:

auth: Basic <token>

BAM login example

The following example assumes there is a running Gateway instance configured to use the BAM service.

{
    "username" : "exampleUser",
    "password" : "examplePassword"
    "bam_alias" : "my bam"
}

If no bam_alias is provided in the API call, Gateway would instead establish a connection to the default BAM configured within Gateway's settings files. If multiple BAMs are configured within Gateway, you can specify the BAM that Gateway should connect to in the API request body, using the BAM alias (bam_alias) for which a token is returned.

Instead of a BAM alias, you can specify a URL for the BAM (bam_url) that is already configured within Gateway. When making an API request using bam_url to the /rest_login endpoint, the payload would look like this:

{
    "username" : "exampleUser",
    "password" : "examplePassword"
    "bam_url" : "http://example.bam.url"
}
Note: You can specify only one of bam_alias and bam_url within the API request for /rest_login, not both.

Before processing the request, Gateway checks to see if the value sent is already configured in Gateway. If it is not, an error response will be returned. Make sure that the BAM details are either configured in api_url in config.py, or provided when you start the Gateway container using environment variables.

The API returns the session token in the following JSON format:

{
    "access_token": "<token>"
}

Users must extract the <token> from the JSON response and insert it in the header of all subsequent requests in the following format:

auth: Basic <token>

Micetro login example

The following example assumes there is a running Gateway instance configured to use the Micetro service.

{
    "username" : "exampleUser",
    "password" : "examplePassword"
    "micetro_alias" : "my micetro server"
}

If no micetro_alias is provided, Gateway will instead connect to the default Micetro instance configured within Gateway. If multiple Micetro instances are configured within Gateway, you can specify the specific instance that Gateway should connect to in the API request body, using the Micetro alias (micetro_alias) for which a token is returned.

Instead of a Micetro alias, you can specify a URL for the Micetro instance (micetro_url) that is already configured within Gateway. When making an API request using micetro_url to the /rest_login endpoint, the payload would look like this:

{
    "username" : "exampleUser",
    "password" : "examplePassword"
    "micetro_url" : "http://example.micetro.url"
}
Note: You can specify only one of micetro_alias and micetro_url within the API request for /rest_login, not both.

Before processing the request, Gateway checks to see if the value sent is already configured in Gateway. If it is not, an error response will be returned. Make sure that the Micetro details are either configured in the micetro key in config.json, or provided when you start the Gateway container using environment variables.