V1 Munic.Connect SSO

Asset visibility  ¶

Currently visibility is managed by the Munic.io Dashboard. As such you must be an API user on the dashboard to use these apis, ask your technical account manager. You will be able to access data for the assets and asset groups you have access to on the dashboard.

Obtaining an access token  ¶

To authenticate to a Munic.io API endpoint, you first need to obtain a MunicConnect access token related to a user account, usually, yours. Username and password are the credentials used to sign in to your MunicConnect account.

Example

curl -H 'Accept: application/json' -F grant_type=password \
-F username={USERNAME} -F password={PASSWORD} \
-X POST https://connect.munic.io/oauth/token

Response (200 OK)

[
  {
    "access_token":"2c622a0eec6c07d20e28bc8eeccd33b679dc15cee3f6d457140...",
    "token_type":"bearer",
    "expires_in":7200,
    "refresh_token":"bfc24f6e1fe8674feb2bd92f0b13127e4aa2f50f6292360b20...",
    "scope":"public",
    "created_at":1520860589
  }
]

Remember, the token is valid 2 hours. Once the timeout is reached your application will have to ask for a new token using the refresh token given with the access token.

Use of the access token  ¶

With your access token, you are now able to use a Munic.io service API. You will have to provide this bearer token through a header attribute - Authorization - in all of your requests. This http authentication scheme is called Bearer authentication.

Authorization: Bearer your_access_token

Getting started  ¶

You first need to register your application on Munic.Connect: registration my application.

Then, get your client_id, client_secret and redirect_uri which are available from the applications page.

Then, the following steps can be followed in order to authenticate the users on your application.

Jwt token  ¶

Munic.Connect generated JWT token. In the rest of this documentation, all examples use a shorter token. A real token is formatted like this :

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsInByb3ZpZGVyIjoibXVuaWMifQ.eyJpc3MiOiJod
HRwczovL2Nvbm5lY3QubXVuaWMuaW8iLCJpYXQiOjE1MzA3OTk5NDcsImp0aSI6IjA1NmFjNDY2L
WEwYzAtNDYyZS05ZTAxLTNmMGNkZGIzM2FhOSIsImV4cCI6MTUzMDgwNzE0Niwic2NvcGUiOiJwd
WJsaWMiLCJ1c2VyIjp7InVpZCI6ImIyNzQyNzM2LWU1MzctOTk5OS1iZDYxLTc4NGI3Njc1OWRmN
yIsImVtYWlsIjoidXNlckBlbWFpbC5jb20ifX0.qfxF8C2qR-VOUIPEetTAGysnkfgnZR1Uqu-Ov
sSJ2Yo

If you decode this token you will obtain information about the user who requested the token.

headers:
{
  "alg": "HS256",
  "typ": "JWT",
  "provider": "munic"
}
payload:
{
  "iss": "https://connect.munic.io",
  "iat": 1530799947,
  "jti": "056ac466-a0c0-462e-9e01-3f0cddb33aa9",
  "exp": 1530807146,
  "scope": "public",
  "user": {
    "uid": "b2742736-e537-9999-bd61-784b76759df7",
    "email": "user@email.com",
    "full_name": "User"
  }
}

Our JWT tokens are encoded using the RS256 ALGORITHM. You will need the following public KEY to verify Munic.connect tokens :

-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAtgH1o4e685fptpO3HT90
hgOLPO5eIkzsef4A21oxHWL66a/2vxiqxUR2cF5cdktxZRk8jE3sYKV7NlsqlYyt
QduiEpcm4VsulOM5AeUXfbegz4hzVjYSUMpk5kDm5CxfLhOU5q8KSMpaDpftyglw
Y3YeiQw5FWvdZ9VlcIRr9NznohXsUyqjt8yV8vhohHcOMM6bcPWrajEnlciS30qf
38QHaaTRa3J9i0wO3+SC+v8/g2pmjvUN7Hs6o9fj+HopjbyDWB0VZ+WqTuC/Hfrk
rRTnuHlv1rG9zQoyxP6tgpKI87lY+fFThd0wachsK5fNoA/0s9x0Ity5YkvFyQrt
XwIDAQAB
-----END PUBLIC KEY-----

Redirect users to request Munic.Connect access  ¶

With this action you can get the authorization related to your application for a user.

GET https://connect.munic.io/oauth/authorize{?client_id,redirect_uri,
response_type}

URI Parameters

An authentication step is needed, the user must sign-in with their Munic.Connect account. After login, Munic.Connect asks the user whether he is willing to grant the permissions that your application is requesting.

With the redirection, you will get an access code uri attribute for your application that can then be used to get an OAuth2 token.

?code=021f3859afb079f0bbcce0e6989dbba4012f7af734cdbf89c82812ee4f750099

Obtain an access token  ¶

You can get a token for your authorized application with this action.

POST https://connect.munic.io/oauth/token{?client_id,client_secret,code,
grant_type,redirect_uri}

URI Parameters

The validity of the token is 2 hours. Once the timeout is reached your application will have to ask for a new token using the refresh token given with the access token.

With the POST action you will get a new token. The answer will contain the following attributes:

Example

{
  "access_token": "dda34d48b088d6e9f79fa3593ed467b249455eb8ba4baa7ed8ab...",
  "refresh_token": "260f5edb10d9b46d348375b1f281b20c0a901de84882caad4a8...",
  "token_type": "bearer",
  "expires_in": 60,
  "scope": "read",
  "created_at": 123456789
}

Refresh the access token, if necessary  ¶

You can get a token using a refresh token previously retrieved. The validity of the token is 2 hours. Once the timeout is reached your application will have to ask for a new token using the refresh token given with the access token.

POST https://connect.munic.io/oauth/token{?client_id,client_secret,
refresh_token,grant_type,redirect_uri}

URI Parameters

With the POST action you will get a new token. The answer will contain the following attributes:

Example

{
  "access_token": "aa45d78e45b55549f79fa3593ed467b2494501de84882caad4...",
  "refresh_token": "4875ab55f447c44d348375b1f281b20c0a901de7444ba7a7f...",
  "token_type": "bearer",
  "expires_in": 60,
  "scope": "read",
  "created_at": 123463999
}

Global information  ¶

A User resource has the following attributes:

• uid - string - unique user id in UUID format. This unique user id must be the primary key for all the services associated with Munic.Connect

• full_name - string

• email - string

• language - string

Content-Type: application/json

Content-Type: application/json

{
  "uid": "fd907347-67c9-4c0c-9452-bffc1d06a4af",
  "full_name": "Robert Tulali",
  "email": "robert.tulali@yoyo.com",
  "language": "english"
}