Authentication API

Overview

AirMap provides an API for authentication which allows users to login to AirMap and receive a token which is required to interact with certain APIs.

https://sso.airmap.io

After obtaining a valid JSON Web Tokens (JWT) by querying the /oauth/ro endpoint, this id_token will have a TTL of 36000 seconds (10 hours) before it expires. To refresh (or generate a new valid token), you can query the /delegation endpoint.

Obtain Token

To get a valid JWT, you can post the https://sso.airmap.io/oauth/ro endpoint with the following parameters:

Name
Located in
Description

grant_type

body

Set to password to authenticate using username/password or urn:ietf:params:oauth:grant-type:jwt-bearer to authenticate using an id_token

client_id

body

Client ID (found in Developer Portal application)

connection

body

Set to Username-Password-Authentication

username

body

Username of AirMap account (URL encoded)

password

body

Password of AirMap account (URL encoded)

scope

body

Leave null to get only an access_token; Set to openid to also retrieve an id_token; Set to openid offline_access to also retrieve an id_token and refresh_token

device

body

String value

Note

It is recommended that the /oauth/ro endpoint should only be queried once to obtain a refresh token for a specific user. After obtaining this refresh token, the application can use it to renew the id token and avoid having to store AirMap login credentials.

Example:

curl -X "POST" "https://sso.airmap.io/oauth/ro" \
	-d "grant_type=password" \
	-d "client_id={CLIENT ID}" \
	-d "connection=Username-Password-Authentication" \
	-d "username={USERNAME}" \
	-d "password={PASSWORD}" \
	-d "scope=openid offline_access" \
	-d "device={DEVICE}"
var request = require('superagent');

request
  .post('https://sso.airmap.io/oauth/ro')
  .send({
      "grant_type": "password",
      "client_id": "{CLIENT_ID}",
      "connection": "Username-Password-Authentication",
      "username": "{USERNAME}",
      "password": "{PASSWORD}",
      "scope": "openid offline_access",
      "device": "{DEVICE}"
})
  .redirects(0)
  .end(function(err, res){
    if (err || !res.ok) {
      console.log(err);
    } else {
      console.log(JSON.stringify(res.body));
    }
  });
#!/usr/bin/env python
"""AirMap Auth0 authentication example"""

import requests

CLIENT_ID = "..."
USER_NAME = "..."
PASSWORD = "..."
DEVICE = "..."
URL = "https://sso.airmap.io/oauth/ro"
PAYLOAD = {
      'grant_type': 'password',
      'client_id': CLIENT_ID,
      'connection': 'Username-Password-Authentication',
      'username': USER_NAME,
      'password': PASSWORD,
      'scope': 'openid offline_access',
      'device': DEVICE
}

R = requests.post(URL, json=PAYLOAD)
print R.status_code
TOKEN = R.json()["id_token"]
print TOKEN
require 'net/http'
require 'net/https'
require 'json'

def send_request
  begin
    uri = URI('https://sso.airmap.io/oauth/ro')

    # Create client
    http = Net::HTTP.new(uri.host, uri.port)
    http.use_ssl = true
    http.verify_mode = OpenSSL::SSL::VERIFY_PEER
    
    dict = {
          "grant_type" => "password",
          "client_id" => "{CLIENT ID}",
          "connection" => "Username-Password-Authentication",
          "username" => "{USERNAME}",
          "password" => "{PASSWORD}",
          "scope" => "openid offline_access",
          "device" => "{DEVICE}"
        }
    body = JSON.dump(dict)

    # Create Request
    req =  Net::HTTP::Delete.new(uri)
    req.body = body

    # Fetch Request
    res = http.request(req)
    puts "Response HTTP Status Code: #{res.code}"
    puts "Response HTTP Response Body: #{res.body}"
  rescue StandardError => e
    puts "HTTP Request failed (#{e.message})"
  end
end

The response contains the valid JWT:

{
    "refresh_token": "afCqG4jj...",
    "id_token": "eyJ0eXAiOiJKV...",
    "access_token": "oGkFH7RDI...",
    "token_type": "bearer"
}

Refresh Token

To refresh your token by generating a new token, you can post the https://sso.airmap.io/delegation endpoint with the following parameters:

grant_type

body

Set to password to authenticate using username/password or urn:ietf:params:oauth:grant-type:jwt-bearer to authenticate using an id_token

client_id

body

Client ID (found in Developer Portal application)

id_token or refresh_token

body

The existing token of the user

Example:

curl -X "POST" "https://sso.airmap.io/delegation" \
	-d "grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer" \
	-d "client_id={CLIENT ID}" \
	-d "refresh_token={REFRESH TOKEN}"
var request = require('superagent');

request
  .post('https://sso.airmap.io/delegation')
  .send({
      "grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer",
      "client_id": "{CLIENT_ID}",
      "refresh_token": "{REFRESH TOKEN}"
})
  .redirects(0)
  .end(function(err, res){
    if (err || !res.ok) {
      console.log(err);
    } else {
      console.log(JSON.stringify(res.body));
    }
  });
import requests

CLIENT_ID = "..."
REFRESH_TOKEN = "..."
DEVICE = "..."
URL = "https://sso.airmap.io/delegation"
PAYLOAD = {
      'grant_type': 'urn:ietf:params:oauth:grant-type:jwt-bearer',
      'client_id': CLIENT_ID,
      'refresh_token': REFRESH_TOKEN
}

R = requests.post(URL, json=PAYLOAD,)
print R.status_code
TOKEN = R.json()["id_token"]
print TOKEN
require 'net/http'
require 'net/https'
require 'json'

def send_request
  begin
    uri = URI('https://sso.airmap.io/delegation')

    # Create client
    http = Net::HTTP.new(uri.host, uri.port)
    http.use_ssl = true
    http.verify_mode = OpenSSL::SSL::VERIFY_PEER
    
    dict = {
          "grant_type" => "password",
          "client_id" => "{CLIENT ID}",
      "refresh_token" => "{REFRESH TOKEN}"
        }
    body = JSON.dump(dict)

    # Create Request
    req =  Net::HTTP::Delete.new(uri)
    req.body = body

    # Fetch Request
    res = http.request(req)
    puts "Response HTTP Status Code: #{res.code}"
    puts "Response HTTP Response Body: #{res.body}"
  rescue StandardError => e
    puts "HTTP Request failed (#{e.message})"
  end
end

The response contains the valid JWT:

{
    "token_type": "Bearer",
    "expires_in": 36000,
    "id_token": "eyJ0eXAiOiJKV..."
}

Updated about a year ago

Authentication API


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.