You have read “Do I Need an Identity API” and decided it makes sense to undertake a small, focused, Proof of Concept (POC) effort with an internal customer or business partner that has the developer resources and desire to work with you. So how do you get started?

puzzle build resized 600


The first step in designing any API is identifying the resources. Being focused on designing an Identity API, this work is largely already done for us. We have things like users, accounts, entitlements, roles, approvers, etc. These are all well-defined and understood concepts in IAM. Pick the subset that makes sense for the particular use case you are targeting in your POC.

The next step in design, and possibly the most challenging, is defining a representation for each of the resources. While you could create your own from scratch, try to reuse existing representation schemas where ever possible. For basic user management, the SCIM standard provides a good basis to work from, but there are others as well that focus on identity-like data, spend some time reviewing what’s available at and The Microformats Wiki.

After deciding on a representation schema, you have another related, but independent decision to make, what media types will you support for the resource representations? JSON? XML? HTML? All of the above based on client preferences and content negotiation? For the purposes of your POC you should probably focus on a single media type, but if you know you will need others down the road, make sure you don’t box yourself in during the implementation phase.

Next up is thinking through your URI design and content linking strategies.

Teams can get stuck in a state of churn at the URI design point, feeling that getting it perfect is critical to the API, when in reality it is just one component of a successful Identity API. Spend some time thinking through it, but not too much, as consistency across your URI’s is the most important thing to focus on.

Links on the other hand often don’t get thought of enough in the initial design. Having a strategy to provide meaningful links between related resources, including link relation types that convey the role or purpose of the link is important. A consistent linking approach across the API will go a long way towards making your API usable to developers.

Lastly, spend some time thinking through not just error handling, but error reporting. In a public facing production deployment, there are certainly security reasons to not divulge too much about what went wrong. Initially though you are trying to get something up and working in as developer friendly manner as possible, the more plain English information you can provide back to the developer about what went wrong and why, the better for everyone.


The choice of technology to implement your design is largely separate from your actual Identity API. From a client/customer developer’s perspective, your API provides platform neutral identity data over HTTP/S using a well-defined URI convention. How you actually go about serving that content has no impact on them.

There are many technology choices available, from writing from scratch to using a REST based framework such as Restlet, Jersey, or ASP.NET Web API. Your organization likely has a preference based on skill sets available that will dictate what you pick. Going with a framework vs. writing from scratch is the preferred route, you want to focus on providing business value through your Identity API, not implementing low level HTTP operations.


When you are in the early stages of designing and implementing your Identity API, security can be a topic that you would rather put off and deal with once you have something working. While you don’t want to over-engineer your security for a POC, by the nature of being an Identity API, this is sensitive data you are providing and following a few practices from the start will save you pain down the road.

  1. Use SSL for everything. Configure your server to redirect any API traffic on the non-SSL port to the SSL port.
  2. While OAuth is great and you hear a lot about it in the context of APIs, in some situations it is overkill. For server-to-server API integrations (the typical case for Identity APIs), two-way SSL, SAML, and even usernames combined with long, random passwords are adequate security schemes that have the advantage of being well supported.

While the above list follows a logical flow familiar to many software development projects, there isn’t one specific path that is “correct” in designing and building an Identity API (or any API). The benefit to starting small and focused is that you will be giving yourself the agility to make changes as you go, and adjust as you learn what is important for your organization. In our next post we will discuss how you take your Identity API prototype, drive developer adoption and create long-term value.


Managed IAM
Andy White

Andy White

Thinking about it I realize that I have been involved with Identity Management for most of my career, and not always intentionally, but hey, that’s ok, I like it. I come from a software development background and love it when I get a chance to get all “technical”, but mostly spend my time helping our Professional Services clients be successful.