Name to agent ID API

From Second Life Wiki
Revision as of 12:18, 13 April 2020 by Oz Linden (talk | contribs) (added a pointer to the equivalent LSL function)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

One of the challenges that will be created by our allowing name changes is that anyone with an external database that uses name lookups will have to adjust by replacing or reindexing to use agent ids. This service is a publicly available rest endpoint to which a user submits a username/last name combination (or a username only with “Resident” the default last name), and is returned the agent_id associated with that name if it exists.

KBnote.png Note: Please do not use this API from LSL: there is a native function that does the same job better - llRequestUserKey

API

Base URL: https://api.secondlife.com/get_agent_id Scheme: HTTP

[POST] /get_agent_id

Provide the agent_id for a given username/lastname combination.

This API allows a user to post a username and lastname (or just a username with Resident the default lastname) and get back a JSON object with the agent id for that name (if it exists).

Parameters

Name Description
api-key
(header, required)
Requests must include a valid API key header. API keys can be obtained at https://accounts.secondlife.com/manage_api_key.
body
(body, required))
The JSON request body containing the username and lastname to inquire about. The last name is optional; if no lastname is provided ‘Resident’ will be used by default.

Example:
{
  "username": "Foo",
  "lastname": "Bar"
}

Responses

Response content type: application/json

Code Description
200 The agent_id for the submitted name was successfully returned.

Example:
application/json
{
  "agent_id": "00000000-0000-0000-0000-000000000001",
  "username": "foo",
  "lastname": "bar"
}
403 Too many requests for this API key (more than 2 per second).
404 The requested user doesn't exist in the system or the API key is invalid.

Examples:
0
{
  "error": "invalid_last_name",
  "message": "Last name Bar is invalid."
}
1
{
  "error": "not_a_user,",
  "message": "No such user Foo"
}
2
{
  "error": "invalid_api_key,",
  "message": "Invalid Key: 00000000-00000000-00000000-00000000"
}
405 The request was not an HTTP POST request.
500 An unexpected error that the application didn't handle occurred.

Models

Request{

username string
(Required; Username or first name of the user whose agent_id we seek)
lastname string
(Not required; Last name of the user whose agent_id we seek. Will default to ‘Resident’ if not provided.)

}

Error{

error string
(Required; an error code unambiguously describing the error.)
message string
(Required; a human-readable description of the encountered error condition.)

}