Is there a single reference that describes the overall model of this API? i.e. there are concepts like Accounts, Projects, Users, Resources, etc that all have some relationship. You get hints of the overall model as you administer the web site or review the API documentation, but it would be nice if it was documented in one place.
In order to consume APIM APIs, you need an APIM account. Signing up to APIM starts the journey with two resources:
-
Account: This is the main structure to contain all resources for your company. You start with a trial account, then can decide to upgrade. -
User: The user who signed up becomes the owner and admin of this account. There are other administrative roles automatically assigned to this first user, such as Billing Admin, Buyer and Project Admin.
This is the atomic state where you can start to consume (some) APIs. For a user, all needed to get authenticated are:
-
Account client ID: The public client ID to be used in OIDC password grant flow. -
Email address and password
You can add other users under your account as well.
So the structure looks like this now:
· Account
o Users[user1,user2,…]
For some of the APIs, like SMS or calls to/from PSTN, you need phone numbers. Account buyer admins can purchase Local or Toll-Free telephone numbers (TNs).
Purchased phone numbers are stored within Account pool until they’re assigned to users (or a project, see below).
So the structure looks like this now:
· Account
o Users[user1,user2,…]
o Resources:
§ TNs[TN1,TN2,…]
In order to use these TNs in APIs, they need to be assigned. If you assign TN1 to user1, then user1 is able to use like SMS API.
So the structure looks like this now:
· Account
o Users[user1,user2,…]
§ User1 – TN1
o Resources:
§ TNs[TN1,TN2,…]
Under account, you can choose to create a project. Project is a resource which can be used to develop a new application, which can contain public clients (such as a mobile app or browser app) and server-side confidential clients of that app. Creation of a project provides the ability of creating project users, configuring mobile push data, creating anonymous call destinations, etc…
· Account
o Users[user1,user2,…]
§ User1 – TN1
o Resources:
§ TNs[TN1,TN2,…]
o Project[project1,project2,…]
With creation of a project, you can consume APIs using project itself. Common use case is building an app like “appointment reminder” where there is no real user behind it. For a project, all needed to get authenticated are:
-
Private project key: The confidential client ID to be used in OIDC client credential grant flow. -
Private project secret: The client secret to be used in OIDC client credential grant flow.
For APIs that require a phone number, projects should be assigned TNs as well, similar to users. Then structure looks like:
· Account
o Users[user1,user2,…]
§ User1 – TN1
o Resources:
§ TNs[TN1,TN2,…]
o Project[project1,project2,…]
§ Project1 – TN2
There are project users, which are targeted to consume the app built under the project. These users are not APIM aware, they only interact with the app itself. That’s why, projects are free to create these users in their desired naming/formatting and do the actual mapping with their actual users out of scope of APIM. With creation of project users, structure looks like:
· Account
o Users[user1,user2,…]
§ User1 – TN1
o Resources:
§ TNs[TN1,TN2,…]
o Project[project1,project2,…]
§ Project1 – TN2
· Users[userA,userB,…]
Finally, accounts can purchase turnkey apps, appears as resources. Structure looks like:
· Account
o Users[user1,user2,…]
§ User1 – TN1
o Resources:
§ TNs[TN1,TN2,…]
§ Apps[app1,app2,…]
o Project[project1,project2,…]
§ Project1 – TN2
· Users[userA,userB,…]
1 Like
@Meron_Elpaz This is really excellent and I appreciate it. I hope this content gets elevated to the Overview section.
There is another level of detail needed to map into the hierarchy you developed. For example, I happen to be trying the SMS service first. It has a notion of a destination_address which is a TN that must be assigned to a Project.
@Dominic_Lunanuova - thanks for the feedback. Yes, we will add it to overview or other general category soon.
in the above, it was mentioned that:
“In order to use these TNs in APIs, they need to be assigned. If you assign TN1 to user1, then user1 is able to use like SMS API.”
You can indeed also assign a number to a project, we will add this to the main post we intend to publish
@Meron_Elpaz I wasn’t clear enough. I was debugging, and in fact utilized the Support Chat for help (Ticket 1964), and was told the TN must be assigned to the Project and not to a User.
@Dominic_Lunanuova - you can assign a TN to a project, to a user (account user), to an application.
The above might be a bit confusing between a project user and an account user - once we publish this we will revisit the wording to make it clearer.