Smart ID

Many API methods take a UserID as one of their required parameters, for example the /badge/give method. Often, especially in a SSO context, the calling system will not know the native Vanilla UserID, but will instead know some other identifying characteristic of the user, such as their Email, Username, or SSO ForeignID.

Fields that accept Smart IDs allow these tokens to be supplied instead of a native UserID. Internally, the Email, Username or SSO ForeignID will be converted into a Vanilla UserID by the API layer and passed along to the core method.

Notation

Passing a Smart ID is easy once you understand Vanilla’s naming conventions, and we’ll explain these from the perspective of the User table: GDN_User.

Table Names

All tables in a Vanilla database are named for their content and use the singular form. In the case of Users, the table is called GDN_User and we refer to it as “the User table”. The Discussion table is called GDN_Discussion, and the Comment table is called GDN_Comment, and so on.

Field Names

The primary key in a given table will always be the table’s name with ID on the end, so in our case, UserID. Even when referring to the User table from another table, we’ll always be careful to make sure that fields containing UserID’s are named ______UserID. For example, the Comment table has a field called InsertUserID.

The User table contains other fields, like Name and Email, and we follow the same referential naming convention for those fields. If there was a field in some table that contained a user’s email address, it would end in UserEmail.

Passing a Smart ID

In our example case where we are trying to pass a UserID, but only have the user’s email, we can instead use a dotted notation to express the table and field we’re passing, and have the API resolve the primary key ID.

UserIDsmart id Required. User. can be passed as

User.Emailstring User’s Email address.

Multi Smart ID

Some API methods require lists of item IDs. The Role parameter of /users/edit is a good example of this. You may want to assign multiple roles to a certain user. Multi Smart ID allows the caller to specify arrays with simple notation.

A normal Smart ID containing a valid RoleID would be passed as Role.ID=56. In order to pass 2 roles, simply pluralize the table name and use commas to separate the values, like this: Roles.ID=56,87. This notation works for other suffixes as well, so to refer to two users by their email addresses the caller might specify: [email protected],[email protected].

SSO ForeignID

The SSO ForeignID type is a special case. It is passed with the parameter name User.ForeignID and its value contains the SSO ClientID (specified in your Vanilla Dashboard) concatenated with the ForeignID (usually the user’s internal ID in your own system, or whatever system is providing SSO), with a colon (:) as the field separator. A simple example is referring to a user by their Facebook email address:

User.ForeignID = Facebook:[email protected] User’s Facebook email address.

In situations where your system is providing SSO services, you would substitute Facebook with your own SSO ClientID. Again, this SSO ClientID can be found in your Vanilla Dashboard under the heading jsConnect (/settings/jsconnect).

Supported Tables

Currently, we support Smart ID for the following tables:

Caveats

Some fields are not unique, so passing them as a Smart ID can be risky and may result in multiple results, and therefore an error. A good example of this is the Name. Vanilla has the option to allow multiple users with the same name, so if at all possible, use Email or SSO ForeignID instead of Name.