Smart IDs - HL Vanilla Community
<main> <article class="userContent"> <p><strong>Higher Logic Vanilla’s (Vanilla)</strong> API v2 supports <strong>smart IDs</strong>. </p><ul><li>These are specially-formatted placeholders that can transparently lookup resource IDs, based on supported criteria. </li></ul><p><strong>⭐️ EXAMPLE</strong>: You can use a smart ID in an API request to look up a Category by its URL code. Another example is to use a smart ID to look up a user based on their SSO foreign IDs.</p><h2 data-id="usage">Usage</h2><p>The basic format of a smart ID is: </p><ul><li><code class="code codeInline" spellcheck="false" tabindex="0">${field}:{value}</code></li></ul><p>“<strong>Field</strong>” is the property you’re attempting the lookup with, while “<strong>value</strong>” is its corresponding criteria. Vanilla will attempt to resolve the smart ID to a specific resource and substitute the row’s primary ID in its place. </p><p><strong>⭐️ EXAMPLE</strong>: Submitting a request to /api/v2/users/<code class="code codeInline" spellcheck="false" tabindex="0">$name:baz</code> will ultimately be dispatched by Vanilla as /api/v2/users/15, where 15 is the ID of a user with the name “baz.” <strong>Do not put a space between the ":" and the value.</strong></p><p>Smart IDs can be used in three areas of a request: </p><ul><li>the path, </li><li>the query, </li><li>and the body. </li></ul><p>When received in one of these areas of a request, Vanilla will attempt to look up the corresponding record, based on the criteria provided.</p><p>Depending on where the smart ID is used, the resolution of the target record ID is dependent on different criteria. </p><p><strong>⭐️ EXAMPLE</strong>: If received in the path, the URL will be used to determine what type of record Vanilla is looking up. A request to /api/v2/users/<code class="code codeInline" spellcheck="false" tabindex="0">$name:foo</code> will attempt to look up a user with the name “foo,” while a request to /api/v2/categories/<code class="code codeInline" spellcheck="false" tabindex="0">$name:foo</code> will attempt to look up a Category with the name “foo.” The same smart ID is used, but the context determines which resource is queried. Similarly, when a smart ID is used in a query or the body of the request, the key of the value is used to resolve the resource. In the case of a smart ID in a query, say /api/v2/discussions?insertUserID=<code class="code codeInline" spellcheck="false" tabindex="0">$name:bar</code>, Vanilla will attempt to look up a user with the name “bar” because the associated key is “insertUserID.” The same request could be modified to /api/v2/discussions?categoryID=<code class="code codeInline" spellcheck="false" tabindex="0">$name:bar</code> and now a Category with the name “bar” will be used.</p><p><strong>📝 NOTE</strong>: If a smart ID resolves to multiple rows, or none at all, a fatal error will be generated. A smart ID must resolve to exactly one row.</p><h2 data-id="supported-fields">Supported fields</h2><p>You can currently use smart IDs with the following resources.</p><h2 data-id="categories">Categories</h2><p>Categories support smart ID lookup using one of two fields:</p><ul><li><strong>name</strong> - The name of a Category.</li><li><strong>urlcode</strong> - The URL code of a Category.</li></ul><h4 data-id="category-smart-id-examples">Category smart ID examples</h4><p><strong>📝 NOTE</strong>: The following examples are not URL-encoding their smart IDs. You must do that when using them.</p><pre class="code codeBlock" spellcheck="false" tabindex="0">// Get discussions by category name. https://example.com/api/v2/discussions?categoryID=$name:Help // Get a single category by URL code. https://example.com/api/v2/categories/$urlcode:support-qna </pre><h2 data-id="users">Users</h2><p>Users support smart ID lookup using one of three fields:</p><ul><li><strong>name</strong> - The name of a user.</li><li><strong>email</strong> - The email address of a user. This field is only accessible if the user submitting the request has the ability to view user email addresses.</li><li>A foreign ID from an SSO connection.</li></ul><h3 data-id="%24me-for-the-current-user">$me for the current user</h3><p><code class="code codeInline" spellcheck="false" tabindex="0">$me</code> can be swapped in for the current session's userID. In the case that a user is a guest and doesn't have an authenticated session, it is equivalent to the guest ID (0).</p><p>Here are a few examples:</p><pre class="code codeBlock" spellcheck="false" tabindex="0">// Get the current users permissions https://example.com/api/v2/users/$me/permissions // Get the current users recent discussions https://example.com/api/v2/discussions?insertUserID=$me&sort-dateInserted </pre><h3 data-id="sso-smart-ids">SSO smart IDs</h3><p>Given the key for an authentication provider, and the foreign ID of a user connected by that provider, you can resolve a foreign ID to a Vanilla user ID.</p><p><strong>⭐️ EXAMPLE</strong>: If a site has an authentication provider with a key of “vanillasso,” you could attempt to look up a user with a foreign ID from that provider by using the following smart ID: <code class="code codeInline" spellcheck="false" tabindex="0">$vanillasso:1234</code>. Vanilla will attempt a lookup of any users connected from “vanillasso” with a foreign ID of 1234. If one is found, their local user ID will be substituted in place of the smart ID. If no matching user is found, an error is encountered. "authprovider" is to be replaced. If you are not sure which key to use for your authentication provider, check your SSO settings and use the ClientID name.</p><div class="embedExternal embedImage display-large float-none"> <div class="embedExternal-content"> <a class="embedImage-link" href="https://us.v-cdn.net/6030677/uploads/817/U6RY87M02UC2.png" rel="nofollow noreferrer noopener ugc" target="_blank"> <img class="embedImage-img" src="https://us.v-cdn.net/6030677/uploads/817/U6RY87M02UC2.png" alt="Screen Shot 2019-07-25 at 6.24.52 PM.png" height="534" width="2004" loading="lazy" data-display-size="large" data-float="none"></img></a> </div> </div> <p>It can be challenging to figure out the client ID of your SSO provider. Here are a few places to check:</p><ul><li><strong>OAuth</strong>: This is your client ID when you edit the connection.</li><li><strong>jsConnect</strong>: This is your client ID when you edit the connection.</li><li><strong>SAML</strong>: This is usually just the single string "samlsso," but the client ID can be changed.</li></ul><p>Here is an example of an endpoint to get a user's info based on their SSO SmartID:</p><pre class="code codeBlock" spellcheck="false" tabindex="0">https://valerie.vanillademo.com/api/v2/users/$vanillasso:1234 </pre><h2 data-id="roles">Roles</h2><p>Categories support smart ID lookup using the <code class="code codeInline" spellcheck="false" tabindex="0">name</code> field.</p><h4 data-id="role-smart-id-example">Role smart ID example</h4><pre class="code codeBlock" spellcheck="false" tabindex="0">// Fetch a list of admin users. https://example.com/api/v2/users?roleID=$name:admin </pre><p><br></p> </article> </main>