Need help with globalid?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

808 Stars 94 Forks MIT License 251 Commits 2 Opened issues


Identify app models with a URI

Services available


Need anything else?

Contributors list

Global ID - Reference models by URI

A Global ID is an app wide URI that uniquely identifies a model instance:


This is helpful when you need a single identifier to reference different classes of objects.

One example is job scheduling. We need to reference a model object rather than serialize the object itself. We can pass a Global ID that can be used to locate the model when it's time to perform the job. The job scheduler doesn't need to know the details of model naming and IDs, just that it has a global identifier that references a model.

Another example is a drop-down list of options, consisting of both Users and Groups. Normally we'd need to come up with our own ad hoc scheme to reference them. With Global IDs, we have a universal identifier that works for objects of both classes.



into any model with a
class method. Support is automatically included in Active Record.
person_gid = Person.find(1).to_global_id
# => # # "gid://app/Person/1"

GlobalID::Locator.locate person_gid

=> #<0x007fae94bf6298>


Signed Global IDs

For added security GlobalIDs can also be signed to ensure that the data hasn't been tampered with.

person_sgid = Person.find(1).to_signed_global_id
# => #<0x007fea1944b410>

person_sgid = Person.find(1).to_sgid

=> #<0x007fea1944b410>


=> "BAhJIh5naWQ6Ly9pZGluYWlkaS9Vc2VyLzM5NTk5BjoGRVQ=--81d7358dd5ee2ca33189bb404592df5e8d11420e"

GlobalID::Locator.locate_signed person_sgid

=> #<0x007fae94bf6298>



Signed Global IDs can expire some time in the future. This is useful if there's a resource people shouldn't have indefinite access to, like a share link.

expiring_sgid = Document.find(5).to_sgid(expires_in: 2.hours, for: 'sharing')
# => #<0x008fde45df8937 ...>

Within 2 hours...

GlobalID::Locator.locate_signed(expiring_sgid.to_s, for: 'sharing')

=> #<0x007fae94bf6298>

More than 2 hours later...

GlobalID::Locator.locate_signed(expiring_sgid.to_s, for: 'sharing')

=> nil


In Rails, an auto-expiry of 1 month is set by default. You can alter that deal in an initializer with:

# config/initializers/global_id.rb
Rails.application.config.global_id.expires_in = 3.months

You can assign a default SGID lifetime like so:

SignedGlobalID.expires_in = 1.month

This way any generated SGID will use that relative expiry.

It's worth noting that expiring SGIDs are not idempotent because they encode the current timestamp; repeated calls to

will produce different results. For example, in Rails
Document.find(5).to_sgid.to_s == Document.find(5).to_sgid.to_s
# => false

You need to explicitly pass

expires_in: nil
to generate a permanent SGID that will not expire,
# Passing a false value to either expiry option turns off expiration entirely.
never_expiring_sgid = Document.find(5).to_sgid(expires_in: nil)
# => #<0x008fde45df8937 ...>

Any time later...

GlobalID::Locator.locate_signed never_expiring_sgid

=> #<0x007fae94bf6298>


It's also possible to pass a specific expiry time

explicit_expiring_sgid = SecretAgentMessage.find(5).to_sgid(expires_at: 1))
# => #<0x008fde45df8937 ...>

1 hour later...

GlobalID::Locator.locate_signed explicit_expiring_sgid.to_s

=> nil


Note that an explicit

takes precedence over a relative


You can even bump the security up some more by explaining what purpose a Signed Global ID is for. In this way evildoers can't reuse a sign-up form's SGID on the login page. For example.

signup_person_sgid = Person.find(1).to_sgid(for: 'signup_form')
# => #<0x007fea1984b520 globalid::locator.locate_signed for:> #<0x007fae94bf6298>

Locating many Global IDs

When needing to locate many Global IDs use

for Signed Global IDs to allow loading Global IDs more efficiently.

For instance, the default locator passes every

thus using
model_name.where(id: model_ids)

In the case of looking up Global IDs from a database, it's only necessary to query once per

as shown here:
gids = users.concat(people).sort_by(&:id).map(&:to_global_id)
# => [#<0x00007ffd6a8411a0 gid:>>,
#<0x00007ffd675d32b8 gid:>>,
#<0x00007ffd6a840b10 gid:>>,
#<0x00007ffd675d2c28 gid:>>,
#<0x00007ffd6a840480 gid:>>,
#<0x00007ffd675d2598 gid:>>]

GlobalID::Locator.locate_many gids

SELECT "users".* FROM "users" WHERE "users"."id" IN ($1, $2, $3) [["id", 1], ["id", 2], ["id", 3]]

SELECT "students".* FROM "students" WHERE "students"."id" IN ($1, $2, $3) [["id", 1], ["id", 2], ["id", 3]]

=> [#, #, #, #, #, #]


Note the order is maintained in the returned results.

Custom App Locator

A custom locator can be set for an app by calling

and providing an app locator to use for that app. A custom app locator is useful when different apps collaborate and reference each others' Global IDs. When finding a Global ID's model, the locator to use is based on the app name provided in the Global ID url.

A custom locator can either be a block or a class.

Using a block:

GlobalID::Locator.use :foo do |gid|

Using a class:

GlobalID::Locator.use :bar,
class BarLocator
  def locate(gid) name: gid.model_name, id: gid.model_id

After defining locators as above, URIs like "gid://foo/Person/1" and "gid://bar/Person/1" will now use the foo block locator and

respectively. Other apps will still keep using the default locator.

Contributing to GlobalID

GlobalID is work of many contributors. You're encouraged to submit pull requests, propose features and discuss issues.



GlobalID is released under the MIT License.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.