Skip to content

IDP API : Tenants

Jump to bottom
Amit Bhadoria edited this page Mar 3, 2016 · 11 revisions

API Title : Tenant management APIs for IDP Service
API Version: /api/v1/
RBAC Policy: Following access checks apply:

  • all API request must have an access token from a user account with role USER for tenant devnet.integratingfactor.com
  • for tenant creation and update API calls, access token should have been issued to client Id with scope REGISTRAR
  • for an existing tenant's user role management user should have role ADMIN for the tenant that is being managed

Tenant Registration APIs

POST /tenants/ -- create a new tenant registration

Bearer token should meet following requirements:

  • issued to a service app what is part of developer org
  • issued by a user that has 'ADMIN` role for the developer org
  • basically this means that new tenant can only be created via iF Studio, which uses resource owner password grant for appropriate access token to meet this RBAC requrement
@IdpRbacPolicy(orgs = { "devnet-alpha.integratingfactor.com", "devnet.integratingfactor.com" }, roles = "ADMIN", scopes = "registrar")

REQUEST:

POST /api/v1/tenants HTTP/1.1
Host: localhost:8080
Authorization: Bearer 9d8a794a-b023-4adb-864b-efa4845fae5c
Content-Type: application/json
Cache-Control: no-cache

{
  "account_id": "119edc86-3d49-4436-80bc-0200065007f0",
  "org_name" : "test org",
  "org_info" : "testing org registration",
  "org_roles": [
    {
       "role_name": "LOANEE",
       "role_description": "person giving out a loan"
    }
  ],
  "org_quota" : {
    "org_type" : "free",
    "max_endpoints" : 2,
    "max_backends" : 1,
    "max_services" : 0,
    "max_admins" : 2,
    "max_users" : 1000
  }
}

RESPONSE:

{
    "org_id": "7b24cf41-58e9-4f27-b08c-8162adff2e34",
    "org_name": "test org",
    "org_info": "testing org registration",
    "org_type" : "free"
}

GET /tenants/ -- get all tenants that user can administer

Bearer token should meet following requirements:

  • issued to an app what is part of developer org (e.g., iF Studio Endpoint UI), or a service app for premium projects
  • issued to a user that has registered as a developer
@IdpRbacPolicy(orgs = { "devnet-alpha.integratingfactor.com", "devnet.integratingfactor.com" }, roles = "USER")

REQUEST:

GET /api/v1/tenants HTTP/1.1
Host: localhost:8080
Authorization: Bearer 9d8a794a-b023-4adb-864b-efa4845fae5c
Content-Type: application/json
Cache-Control: no-cache

RESPONSE:

[
    {
        "org_id": "7b24cf41-58e9-4f27-b08c-8162adff2e34",
        "org_name": "test org",
        "org_info": "testing org registration",
        "org_type" : "free"
    },
    {
        "org_id": "51c53f48-fa9a-42bb-b57c-e1a96046c22c",
        "org_name": "test org",
        "org_info": "testing org registration"
        "org_type" : "free"
    }
]

GET /tenants/{tenantId} -- get specified tenant details

Bearer token should meet following requirements:

  • issued to an app what is part of developer org (e.g., iF Studio Endpoint UI), or a service app for premium projects
  • issued to a user that has registered as a developer
@IdpRbacPolicy(orgs = { "devnet-alpha.integratingfactor.com", "devnet.integratingfactor.com" }, roles = "USER")

REQUEST:

GET /api/v1/tenants/3407cce6-a82d-438f-9997-dc318bc95a25 HTTP/1.1
Host: localhost:8080
Authorization: Bearer 7f516bfb-296f-4227-8204-e8ad64129ded
Content-Type: application/json
Cache-Control: no-cache

RESPONSE:

{
  "org_name" : "test org",
  "org_info" : "testing org registration",
  "org_quota" : {
    "org_type" : "free",
    "max_endpoints" : 2,
    "max_backends" : 1,
    "max_services" : 0,
    "max_admins" : 2,
    "max_users" : 1000
  },
  "org_roles": [
    {
       "role_name": "LOANEE",
       "role_description": "person giving out a loan"
    }
  ]
}

PUT /tenants/{tenantId} -- update specified tenant details (new roles get added, existing role gets updated)

Bearer token should meet following requirements:

  • issued to a service app what is part of developer org
  • issued by a user that has 'ADMIN` role for the developer org
  • basically this means that new tenant can only be created via iF Studio, which uses resource owner password grant for appropriate access token to meet this RBAC requrement
@IdpRbacPolicy(orgs = { "devnet-alpha.integratingfactor.com", "devnet.integratingfactor.com" }, roles = "ADMIN", scopes = "registrar")

REQUEST:

PUT /api/v1/tenants/3407cce6-a82d-438f-9997-dc318bc95a25 HTTP/1.1
Host: localhost:8080
Authorization: Bearer 7f516bfb-296f-4227-8204-e8ad64129ded
Content-Type: application/json
Cache-Control: no-cache

{
  "org_name" : "test org 2",
  "org_info" : "updating org registration",
  "org_roles": [
    {
       "role_name": "LOANER",
       "role_description": "person taking a loan"
    }
  ]
  "org_quota" : {
    "org_type" : "free",
    "max_endpoints" : 2,
    "max_backends" : 1,
    "max_services" : 0,
    "max_admins" : 2,
    "max_users" : 1000
  }
}

RESPONSE:

{
    "org_id": "3407cce6-a82d-438f-9997-dc318bc95a25",
    "org_name": "test org 2",
    "org_info": "updating org registration"
}

Tenant User Roles Management APIs

GET /tenants/{tenantId}/users?role={roleType}

get all users of specified role type
REQUEST:

GET /api/v1/tenants/ead4df36-4613-427c-b547-1ceca62a72eb/users?role=ADMIN HTTP/1.1
Host: localhost:8080
Authorization: Bearer 7bf1b2e9-53b6-4391-ad57-2fb6b0433274
Content-Type: application/json
Cache-Control: no-cache

RESPONSE:

[
    {
        "account_id": "119edc86-3d49-4436-80bc-0200065007f0",
        "user_roles": [
            "ADMIN"
        ]
    }
]

PUT /tenants/{tenantId}/users/{accountId}

update user roles for specified users and their roles (will not remove old roles if ommitted in update request)
REQUEST:

PUT /api/v1/tenants/e3f98c67-650f-4d6f-9411-f4e0f2c25728/users/119edc86-3d49-4436-80bc-0200065007f0 HTTP/1.1
Host: localhost:8080
Authorization: Bearer 694aeb6e-bee3-4fdd-bca0-d8ac08ffe22d
Content-Type: application/json
Cache-Control: no-cache

{ "account_id": "119edc86-3d49-4436-80bc-0200065007f0", "user_roles": [ "USER" ] }

RESPONSE:

[
    {
        "account_id": "119edc86-3d49-4436-80bc-0200065007f0",
        "user_roles": [
            "ADMIN",
            "USER"
        ]
    }
]

DELETE /tenants/{tenantId}/users/{accountId}

remove a user from tenant
REQUEST:

DELETE /api/v1/tenants/2710730b-f966-49bd-95fc-2dfb461f8dfa/users/119edc86-3d49-4436-80bc-0200065007f0 HTTP/1.1
Host: localhost:8080
Authorization: Bearer 849a0ae6-4cd3-4ba8-a786-672f65e21000
Content-Type: application/json
Cache-Control: no-cache

RESPONSE:

204 No Content

Tenant User Provisioning APIs

PUT /tenants/{tenantId}/approvals

Provision users with specific role, using their identities, for an org/tenant that have explicit user role policy
REQUEST:

PUT /api/v1/tenants/85043c1b-f2a0-4a14-89f8-7b354a77723e/approvals HTTP/1.1
Host: localhost:8080
Authorization: Bearer 2590ae72-6ebe-4f22-8ee5-e82ddbe24437
Content-Type: application/json
Cache-Control: no-cache


[
  {
  "id_key" : "test@gmail.com",
  "id_type" : "email",
  "user_roles" : [
    "USER"
    ]
  },
  {
  "id_key" : "admin@gmail.com",
  "id_type" : "email",
  "user_roles" : [
    "USER", "ADMIN"
    ]
  }
]

RESPONSE:

200 OK

GET /tenants/{tenantId}/approvals?role={roleType}

get a list of all pending/unclaimed user approvals for specified role
REQUEST:

GET /api/v1/tenants/9c6fa8cf-ddbb-425a-9957-65a1dd292b3c/approvals?role=USER HTTP/1.1
Host: localhost:8080
Authorization: Bearer 2590ae72-6ebe-4f22-8ee5-e82ddbe24437
Content-Type: application/json
Cache-Control: no-cache

RESPONSE:

[
  {
  "id_key" : "test@gmail.com",
  "id_type" : "email",
  "user_roles" : [
    "USER"
    ]
  },
  {
  "id_key" : "admin@gmail.com",
  "id_type" : "email",
  "user_roles" : [
    "USER"
    ]
  }
]

`PUT /tenants/{tenantId}/approvals/remove

remove pending user approvals (this removes pending approval for specified roles in request, if there are other pending approvals with roles not listed in request, then they will not be removed)
REQUEST:

PUT /api/v1/tenants/85043c1b-f2a0-4a14-89f8-7b354a77723e/approvals/remove HTTP/1.1
Host: localhost:8080
Authorization: Bearer 2590ae72-6ebe-4f22-8ee5-e82ddbe24437
Content-Type: application/json
Cache-Control: no-cache

[
  {
  "id_key" : "admin@gmail.com",
  "id_type" : "email",
  "user_roles" : [
    "USER"
    ]
  }
]

RESPONSE:

204 No Content

Tenant App Registration APIs

GET /tenants/{tenantId}/apps

get all apps registered with the tenant
REQUEST:

GET /api/v1/tenants/9443defe-de84-4346-8b6b-1256c7bea06a/apps/ HTTP/1.1
Host: localhost:8080
Authorization: Bearer 08772480-9efb-4f65-90b3-84aababc5570
Content-Type: application/json
Cache-Control: no-cache

RESPONSE:

[
    {
        "client_id": "0a6f41c0-da71-4942-9de7-caadea5b5614",
        "app_type": "backend_app",
        "redirect_urls": [
            "http://localhost:8080"
        ],
        "registered_scopes": [
            "validation",
            "openid"
        ],
        "app_name": " backend app",
        "app_info": "an updated test app for testing"
    },
    {
        "client_id": "9bdb4345-cc71-4edf-9acb-68f75c17917c",
        "app_type": "endpoint_app",
        "redirect_urls": [
            "http://localhost:8080"
        ],
        "registered_scopes": [
            "endpoint"
        ],
        "app_name": "mobile app",
        "app_info": "a mobile app to access endpoint"
    }
]

POST /tenants/{tenantId}/apps

create a new app registration with details specified in request body
REQUEST:

POST /api/v1/tenants/28351993-4d04-46c6-8563-3d041873d546/apps HTTP/1.1
Host: localhost:8080
Authorization: Bearer 2a71f285-761c-485a-8dea-9fd26512d286
Content-Type: application/json
Cache-Control: no-cache


{
  "app_type" : "backend_app",
  "app_secret" : "Secret123",
  "redirect_urls" : [
    "http://localhost:8080"
    ],
  "privacy_url" : "http://localhost:8080/privacy.html",
  "app_name" : "test app",
  "app_info" : "a test app for testing"
}

RESPONSE:

{
    "client_id": "67eba65f-5f21-4c24-8652-635b7b9a876b",
    "app_type": "backend_app",
    "redirect_urls": [
        "http://localhost:8080"
    ],
    "privacy_url": "http://localhost:8080/privacy.html",
    "app_secret": "Secret123",
    "registered_scopes": [
        "validation",
        "openid"
    ],
    "app_name": "test app",
    "app_info": "a test app for testing"
}

GET /tenants/{tenantId}/apps/{clientId}

get specific app registration with details in request body
REQUEST:

GET /api/v1/tenants/28351993-4d04-46c6-8563-3d041873d546/apps/6299d8f7-6fe9-42ab-a988-ea3a9a2a56c9 HTTP/1.1
Host: localhost:8080
Authorization: Bearer 2a71f285-761c-485a-8dea-9fd26512d286
Content-Type: application/json
Cache-Control: no-cache

RESPONSE:

{
    "client_id": "6299d8f7-6fe9-42ab-a988-ea3a9a2a56c9",
    "app_type": "backend_app",
    "redirect_urls": [
        "http://localhost:8080"
    ],
    "privacy_url": "http://localhost:8080/privacy.html",
    "app_secret": "Secret123",
    "registered_scopes": [
        "validation",
        "openid"
    ],
    "app_name": "test app",
    "app_info": "a test app for testing"
}

PUT /tenants/{tenantId}/apps/{clientId}

update app registration with details specified in request body
REQUEST:

PUT /api/v1/tenants/9443defe-de84-4346-8b6b-1256c7bea06a/apps/9bdb4345-cc71-4edf-9acb-68f75c17917c HTTP/1.1
Host: localhost:8080
Authorization: Bearer 08772480-9efb-4f65-90b3-84aababc5570
Content-Type: application/json
Cache-Control: no-cache

{
    "app_type": "endpoint_app",
    "redirect_urls": [
      "xyz:wewe:sdsw"
    ],
    "privacy_url": "http://localhost:8080/privacy.html",
    "registered_scopes": [
        "validation",
        "openid",
        "registrar"
    ],
    "app_name": "updated mobile app",
    "app_info": "an updated mobile app to access endpoint"
}

RESPONSE:

{
    "client_id": "9bdb4345-cc71-4edf-9acb-68f75c17917c",
    "app_type": "endpoint_app",
    "redirect_urls": [
        "xyz:wewe:sdsw"
    ],
    "privacy_url": "http://localhost:8080/privacy.html",
    "registered_scopes": [
        "endpoint"
    ],
    "app_name": "updated mobile app",
    "app_info": "an updated mobile app to access endpoint"
}

DELETE /tenants/{tenantId}/apps/{clientId}

remove an app registration from tenant
REQUEST:

DELETE /api/v1/tenants/9443defe-de84-4346-8b6b-1256c7bea06a/apps/9bdb4345-cc71-4edf-9acb-68f75c17917c HTTP/1.1
Host: localhost:8080
Authorization: Bearer 08772480-9efb-4f65-90b3-84aababc5570
Content-Type: application/json
Cache-Control: no-cache

RESPONSE:

204 No Content

© 2015-2016 · Integratingfactor.com

Clone this wiki locally