REST API usage in the BlueCat Web Framework - Platform - BlueCat Gateway - 25.3.0

Gateway Administration Guide
ft:locale
en-US
Product name
BlueCat Gateway
Version
25.3.0

Users can use the POST /rest_login API endpoint to log in to BlueCat Address Manager (BAM), Micetro, or Gateway directly (when using Standalone authentication).

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

<bluecat_gateway_address>/rest_login

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

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

When authenticating with BAM or Micetro, if the user sends only the username and password when accessing the /rest_login endpoint, BlueCat Gateway will use 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.

    To override the default, include the bam_url or bam_alias setting in the request payload.

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

    To override the default, include the micetro_url or micetro_alias setting in the request payload.

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.

When using Standalone authentication, Gateway is not connecting to another server. No additional URL or alias setting is needed.

If authentication was successful, the call to rest_login returns a 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>
Note: When using custom authentication extensions with Standalone authentication, users can still log in to the UI through the REST API.

When overriding the default Gateway Standalone authentication with your own custom authentication functions, users can still log in to Gateway from the UI or the POST /rest_login API endpoint. There is no difference in behavior.

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.