Linden Lab Official:Registration API Reference: Difference between revisions

From Second Life Wiki
Jump to navigation Jump to search
Newer edit →
Rand Linden (talk | contribs)
9,923 edits
New page: To gain the capability URL for each service, POST your Second Life "first_name", "last_name", and "password" to https://cap.secondlife.com/get_reg_capabilities. For more information on ca...
 
Rand Linden (talk | contribs)
9,923 edits
No edit summary
(22 intermediate revisions by the same user not shown)
Line 1: Line 1:
To gain the capability URL for each service, POST your Second Life "first_name", "last_name", and "password" to https://cap.secondlife.com/get_reg_capabilities.
{{:Web Services Portal/navigation}}


For more information on capability URLs, see [[Registration_API#Using_capability_URLs|Using capability URLs]].
== add_to_group ==
 
'''HTTP method''': POST
 
The add_to_group operation adds a new Resident (user) to the specified group. 
 
NOTE: This operation will work for one hour after a user initially registers.  After that time, the operation will have no effect for that user.
 
To use this operation, you must:
 
* Receive the "add_to_group" capability ''before'' the user registers.
* Have a role in the group with the ability to add Residents to the group, shown in the Viewer as ability "Invite People to this Group."  For more information, see [[Group Roles]] Knowledge Base article.
** The group owner always has this ability
** By default, officers have it.
** Other group members may have the ability, if they have a role for which it has been granted. 
 
* Register the user yourself using your granted capabilities.
 
=== Parameters ===
 
POST an LLSD map containing the user's first and last name and the group name and the Reg API returns a Boolean value indicating whether the operation was successful.
 
{| border="1" class="lltable"
!Parameter !!  Data type !! Description !! Default Value
 
|---
| first
| String
| User's first name
| None. Required parameter.
 
|---
| last
| String
| User's last name
| None. Required parameter.
 
|---
| group_name
| String
| Group name
| None. Required parameter.
|}
 
=== Return value ===
The Reg API returns an LLSD document containing a Boolean value that indicates whether the operation was successful.  If the value is "true" then the Resident was added to the specified group.
 
=== Example ===
Posted message:
 
<llsd>
    <map>
        <key>first</key>
        <string>Noobie</string>
        <key>last</key>
        <string>Filbert</string>
        <key>group_name</key>
        <string>Cool Group</string>
    </map>
</llsd>
 
If the Resident was successfully added to the group, Reg API returns the following:
 
<llsd>
  <boolean>true</boolean>
</llsd>
 
== check_name ==
 
'''HTTP method''': POST
 
The check_name operation checks to see if a user can be registered with a given Second Life first name and last name.
 
=== Parameters ===
 
POST the new user's desired "username" and "last_name_id", and the Reg API returns an LLSD document that contains a Boolean value indicating whether the name is available.
 
{| {{Prettytable}}
|-{{Hl2}}
!Setting !!  Data type !! Description !! Default Value


== GET operations ==
|---
| username
| String
| Desired user name (Second Life first name). Must be between 2-31 alphanumeric characters.  Certain first names are restricted; for example, those considered obscene or inappropriate for public use.
| Required parameter.


=== get_last_names ===
|---
| last_name_id
| Integer
| ID of desired Second Life last name. 
| Required parameter.


The get_last_names operation retrieves the last names and corresponding IDs with which you are able to register new users.
|}


Example GET Response:
=== Example ===
Posted message:


  <llsd>  
  <llsd>  
   <map>  
   <map>  
       <key>1926</key><string>Morellet</string>  
       <key>username</key><string>mistaht</string>  
       <key>1683</key><string>Okamoto</string>
       <key>last_name_id</key><integer>1872</integer>  
      <key>1738</key><string>Rankin</string>
...
      <key>1870</key><string>Yang</string>  
   </map>  
   </map>  
  </llsd>
  </llsd>


===get_error_codes ===
Reply message:
 
<llsd>
  <boolean>true</boolean>
</llsd>
 
== create_user ==
 
'''HTTP method''': POST
 
The create_user operation creates a new Second Life Resident (user) account.  POST to this URL a LLSD document containing at least the following parameters:
* username
* last_name_id
* email 
* dob
* password
 
In addition, you can include any of the optional parameters listed in the table below.
 
If successful, the Reg API will return a hash containing the new user's agent_id. If there are errors, the Reg API will instead return an array containing the applicable error codes will be returned.
 
=== Parameters===


The get_error_codes operation returns an LLSD document describing the Reg API error codes. This information is reproduced in [[Registration API Error Codes]].
{| {{Prettytable}}
|-{{Hl2}}
!Setting !! Data type !! Description !! Default Value


The errors are in an array, and each error is, in addition, contained in an array. The first element in the array is the error code, the second is the name of the error, the third is the description.
|---
| username
| String
| Desired user name (Second Life first name). Must be between 2-31 alphanumeric characters.  Certain first names are restricted; for example, those considered obscene or inappropriate for public use.
| Required parameter.
 
|---
| last_name_id
| Integer
| ID of desired Second Life last name. 
| Required parameter.
 
|---
| email
| String
| User's email address.
| Required parameter.
 
|---
| password
| String
| Desired password. Must be between 6-16 characters. 
| Required parameter.
 
|---
| dob
| String
| User's date of birth in the YYYY-MM-DD format. Users under 18 cannot be registered to the mainland.  See limited_to_estate. 
| Required parameter.
 
|---
 
| limited_to_estate
| Integer
| ID of estate that the user will be limited to.  To change this to another estate, you must own the estate.  Optional parameter.
| Estate 1, the mainland.
 
|---
| start_region_name
| String
| Region where user will initially appear after login. This can only be set to simulators in the user's limited to estate.  Optional parameter.
| Orientation island of the estate.
 
|---
| start_local_x
| Float
| X coordinate of the starting region. Must be between 0-256.  Value must have two decimal places, for example: 123.00. 
Optional parameter; valid only when start_region_name is set. 
| 128 (center).


Example GET response:
|---
| start_local_y
| Float
| Y coordinate of the starting region.  Must be between 0-256. Value must have two decimal places, for example: 123.00.
Optional parameter; valid only when start_region_name is set.
| 128 (center).


<llsd>
|---
    <array>
| start_local_z
        <array>
| Float
            <integer>10</integer>
| Z coordinate of the starting region. Must be between 0-256. Value must have two decimal places, for example: 123.00.
            <string>invalid flow</string>
Optional parameter; valid only when start_region_name is set. 
            <string>The registration flow does not exist</string>
| 128 (center).
        </array>
        <array>
            <integer>20</integer>
            <string>missing required field</string>
            <string>You are missing one of the required fields</string>
        </array>
  ...  
        <array>
            <integer>1500</integer>
            <string>malformed xml</string>
            <string>Your xml is malformed</string>
        </array>
    </array>
</llsd>


== POST operations ==
|---
| start_look_at_x
| Float
| X component of the unit vector representing initial look direction.  Must be between 0-1. 
Optional parameter; valid only when start_region_name is set. 
| 0


=== create_user ===
|---
| start_look_at_y
| Float
| Y component of the unit vector representing initial look direction. Must be between 0-1. 
Optional parameter; valid only when start_region_name is set.
| 1


The create_user operation creates a new Second Life user.
|}


* POST to this url a LLSD XML document, representing a hash, containing at least "username" (string), "last_name_id" (integer), "email" (string), "dob" (string in YYYY-MM-DD format), "password" (string)
NOTE: You can get the numeric estate ID via the debug menus (Ctrl+Alt+Shift+D to enable them). Then use Client > View Admin Options.  This will allow you to view, but not use, the options that admins (Lindens) can use. Now go to the Server menu, which appeared with the Client one.  Select God Tools, look at the Region tab...  the Estate ID is listed there. Don't worry about pressing or changing something you shouldn't... as they are just viewable options, any changes you make won't stick.
* Optional arguments are "limited_to_estate" (integer), "start_region_name" (string), "start_local_x" (float between 0-128), "start_local_y", "start_local_z", "start_look_at_x" (float between 0-1), "start_look_at_y", "start_look_at_z"
* If all is successful, a hash containing the new user's agent_id will be returned. If there are errors, instead an array containing the applicable error codes will be returned.


POST Parameters
===Return value===


Map
If the operation successfully creates a new user, it returns a document like this:
* key: username
** value (String): Desired username (i.e. SL first name). Between 2-31 alpha-numeric characters.
* key: last_name_id
** value (Integer): ID of desired SL last name.
* key: email
** value (String): Users email address.
* key: password
** value (String): Desired password. Between 6-16 characters.
* key: dob
** value (String): Users date of birth in the YYYY-MM-DD format.. Users under 18 cannot be registered to the mainland (see limited_to_estate)


* limited_to_estate (not required)
<llsd>
** value (Integer): ID of estate that the user will be limited to. Default is estate 1, the mainland. To change this to another estate, you must own the estate.
  <map>
*** ''You can get the numeric estate ID via the debug menus (Ctrl+Alt+Shift+D to enable them). Then use Client > View Admin Options.  This will allow you to view, but not use, the options that admins (Lindens) can use. Now go to the Server menu, which appeared with the Client one.  Select God Tools, look at the Region tab...  the Estate ID is listed there. Don't worry about pressing or changing something you shouldn't...  as they are just viewable options, any changes you make won't stick.'' -- Spike Linden
      <key>agent_id</key>
* start_region_name (not required)
      <string>''UNIQUE_ID''</string>
** value (String): Name of the region that the user will be initially teleported to. Default is the orientation island of the estate. This can only be set to simulators in the user's limited to estate.
  </map>
* start_local_x (not required)
</llsd>
** value (Float): X coordinate of the region that the user will be teleported to.Between 0-256. Default is 128 (center). This parameter is ignored unless start_region_name is set.
* start_local_y (not required)
** value (Float): Y coordinate of the region that the user will be teleported to.Between 0-256. Default is 128 (center). This parameter is ignored unless start_region_name is set.
* start_local_z (not required)
** value (Float): Z coordinate of the region that the user will be teleported to.Between 0-256. Default is 128 (center). This parameter is ignored unless start_region_name is set.
* start_look_at_x (not required)
** value (Float): X component of the unit vector representing initial look direction.Between 0-1. Default is 0. This parameter is ignored unless start_region_name is set.
* start_look_at_y (not required)
** value (Float): Y component of the unit vector representing initial look direction.Between 0-1. Default is 1. This parameter is ignored unless start_region_name is set.
* start_look_at_z (not required)
** Currently z component is ignored (set to 0).


Return Value
Where ''UNIQUE_ID'' is the new user's unique Second Life ID number.


Map - If user creation is sucessful, a map with the new user's information is returned
If the operation is not successful, then it returns an array of error codes similar to that returned by [[#get_error_codes|get_error_codes]].
* key: agent_id
** value (Integer): ID of new SL user.
or


* Array - If user creation fails, an array of error code(s) is returned.
=== Example ===
** Integer - Represents an error code (see get error codes)


Example Posted Message:
Posted message:


  <llsd>
  <llsd>
Line 115: Line 245:
  </llsd>
  </llsd>


Example Reply Message:
Reply message:


  <llsd>  
  <llsd>  
Line 124: Line 254:
  </llsd>
  </llsd>


=== check_name ===
== get_error_codes ==
 
'''HTTP method''': GET
 
The get_error_codes operation returns an LLSD document describing the Reg API error codes.  This information is reproduced in [[Registration API Error Codes]].  This operation does not take any parameters.
 
The errors are in an array, and each error is, in addition, contained in an array. The first element in the array is the error code, the second is the name of the error, the third is the description.
 
=== Example ===
The following HTML code illustrates a simple form to get the error codes:
 
<form action="<nowiki>https://cap.secondlife.com/cap/0/</nowiki>''UUID''" method="GET">
    <input type='submit' value="Get Error Codes">
</form>
 
Example response:
 
<llsd>
    </array>
        <array>
            <integer>20</integer>
            <string>missing required field</string>
            <string>You are missing one of the required fields</string>
        </array>
...
        <array>
            <integer>1500</integer>
            <string>malformed xml</string>
            <string>Your xml is malformed</string>
        </array>
    </array>
</llsd>
 
== get_last_names ==
 
'''HTTP method''': GET
 
The get_last_names operation retrieves the last names and corresponding IDs with which you are able to register new users. 
 
=== Example ===


The check_name operation checks to see if a user can be registered with a given Second Life first name and last name.
The following HTML code illustrates a simple form to get the valid last names:


POST the new user's desired "username" and "last_name_id", and you'll get back LLSD XML, representing a boolean. The same parameter restrictions for the "create user" service apply here.
<form action="<nowiki>https://cap.secondlife.com/cap/0/</nowiki>''UUID''" method="GET">
    <input type="submit" value="Get Last Names">
</form>


Example Posted Message:
Example response:


  <llsd>  
  <llsd>  
   <map>  
   <map>  
       <key>username</key><string>mistaht</string>  
       <key>1926</key><string>Morellet</string>  
       <key>last_name_id</key><integer>1872</integer>  
       <key>1683</key><string>Okamoto</string>
      <key>1738</key><string>Rankin</string>
...
      <key>1870</key><string>Yang</string>  
   </map>  
   </map>  
  </llsd>
  </llsd>


Example Reply Message:
== get_reg_capabilities ==
 
'''HTTP method''': POST
 
This operation returns the capability URL for each operation for which your account is authorized.
 
URI: https://cap.secondlife.com/get_reg_capabilities
 
POST parameters
 
* first_name (Second Life first name)
* last_name (Second Life surname)
* password


<llsd>  
For more information on capability URLs, see [[Registration_API#Using_capability_URLs|Using capability URLs]].
  <boolean>true</boolean>  
 
</llsd>
==DTD==
 
This simplified version of the full [[LLSD#DTD|LLSD DTD]], enables stricter validation of result documents.
 
<div style="font-size:0.9em;"><xml><!DOCTYPE llsd [
<!ELEMENT llsd (map)>
<!ELEMENT map ((key,(string|uri))*)>
<!ELEMENT key (#PCDATA)>
<!ELEMENT string (#PCDATA)>
<!ELEMENT uri (#PCDATA)>
 
<!ATTLIST string xml:space (default|preserve) 'preserve'>
]></xml></div>


[[Category:RegAPI|Documentation]]
[[Category:RegAPI|Documentation]]
[[Category:Web Service APIs]]
[[Category:Web Service APIs]]

Revision as of 15:48, 29 October 2009

add_to_group

HTTP method: POST

The add_to_group operation adds a new Resident (user) to the specified group.

NOTE: This operation will work for one hour after a user initially registers. After that time, the operation will have no effect for that user.

To use this operation, you must:

  • Receive the "add_to_group" capability before the user registers.
  • Have a role in the group with the ability to add Residents to the group, shown in the Viewer as ability "Invite People to this Group." For more information, see Group Roles Knowledge Base article.
    • The group owner always has this ability
    • By default, officers have it.
    • Other group members may have the ability, if they have a role for which it has been granted.
  • Register the user yourself using your granted capabilities.

Parameters

POST an LLSD map containing the user's first and last name and the group name and the Reg API returns a Boolean value indicating whether the operation was successful.

Parameter Data type Description Default Value
first String User's first name None. Required parameter.
last String User's last name None. Required parameter.
group_name String Group name None. Required parameter.

Return value

The Reg API returns an LLSD document containing a Boolean value that indicates whether the operation was successful. If the value is "true" then the Resident was added to the specified group.

Example

Posted message: 

<llsd>
   <map>
       <key>first</key>
       <string>Noobie</string>
       <key>last</key>
       <string>Filbert</string>
       <key>group_name</key>
       <string>Cool Group</string>
   </map>
</llsd>

If the Resident was successfully added to the group, Reg API returns the following: 

<llsd> 
  <boolean>true</boolean> 
</llsd>

check_name

HTTP method: POST

The check_name operation checks to see if a user can be registered with a given Second Life first name and last name.

Parameters

POST the new user's desired "username" and "last_name_id", and the Reg API returns an LLSD document that contains a Boolean value indicating whether the name is available.

Setting Data type Description Default Value
username String Desired user name (Second Life first name). Must be between 2-31 alphanumeric characters. Certain first names are restricted; for example, those considered obscene or inappropriate for public use. Required parameter.
last_name_id Integer ID of desired Second Life last name. Required parameter.

Example

Posted message: 

<llsd> 
  <map> 
      <key>username</key><string>mistaht</string> 
      <key>last_name_id</key><integer>1872</integer> 
  </map> 
</llsd>

Reply message: 

<llsd> 
  <boolean>true</boolean> 
</llsd>

create_user

HTTP method: POST

The create_user operation creates a new Second Life Resident (user) account. POST to this URL a LLSD document containing at least the following parameters:

  • username
  • last_name_id
  • email
  • dob
  • password

In addition, you can include any of the optional parameters listed in the table below.

If successful, the Reg API will return a hash containing the new user's agent_id. If there are errors, the Reg API will instead return an array containing the applicable error codes will be returned.

Parameters

Setting Data type Description Default Value
username String Desired user name (Second Life first name). Must be between 2-31 alphanumeric characters. Certain first names are restricted; for example, those considered obscene or inappropriate for public use. Required parameter.
last_name_id Integer ID of desired Second Life last name. Required parameter.
email String User's email address. Required parameter.
password String Desired password. Must be between 6-16 characters. Required parameter.
dob String User's date of birth in the YYYY-MM-DD format. Users under 18 cannot be registered to the mainland. See limited_to_estate. Required parameter.
limited_to_estate Integer ID of estate that the user will be limited to. To change this to another estate, you must own the estate. Optional parameter. Estate 1, the mainland.
start_region_name String Region where user will initially appear after login. This can only be set to simulators in the user's limited to estate. Optional parameter. Orientation island of the estate.
start_local_x Float X coordinate of the starting region. Must be between 0-256. Value must have two decimal places, for example: 123.00.

Optional parameter; valid only when start_region_name is set.

128 (center).
start_local_y Float Y coordinate of the starting region. Must be between 0-256. Value must have two decimal places, for example: 123.00.

Optional parameter; valid only when start_region_name is set.

128 (center).
start_local_z Float Z coordinate of the starting region. Must be between 0-256. Value must have two decimal places, for example: 123.00.

Optional parameter; valid only when start_region_name is set.

128 (center).
start_look_at_x Float X component of the unit vector representing initial look direction. Must be between 0-1.

Optional parameter; valid only when start_region_name is set.

0
start_look_at_y Float Y component of the unit vector representing initial look direction. Must be between 0-1.

Optional parameter; valid only when start_region_name is set.

1

NOTE: You can get the numeric estate ID via the debug menus (Ctrl+Alt+Shift+D to enable them). Then use Client > View Admin Options. This will allow you to view, but not use, the options that admins (Lindens) can use. Now go to the Server menu, which appeared with the Client one. Select God Tools, look at the Region tab... the Estate ID is listed there. Don't worry about pressing or changing something you shouldn't... as they are just viewable options, any changes you make won't stick.

Return value

If the operation successfully creates a new user, it returns a document like this: 

<llsd> 
  <map> 
      <key>agent_id</key> 
      <string>UNIQUE_ID</string> 
  </map> 
</llsd>

Where UNIQUE_ID is the new user's unique Second Life ID number.

If the operation is not successful, then it returns an array of error codes similar to that returned by get_error_codes.

Example

Posted message: 

<llsd>
  <map>
    <key>dob</key><string>1987-07-06</string>
    <key>start_region_name</key><string>da boom</string>
    <key>username</key><string>mistaht</string>
    <key>last_name_id</key><integer>1872</integer>
    <key>password</key><string>123456</string>
    <key>email</key><string>ben@ben.com</string>
  </map>
</llsd>

Reply message: 

<llsd> 
  <map> 
      <key>agent_id</key> 
      <string>87cfdb64-c852-4359-ae16-dce36099ff68</string> 
  </map> 
</llsd>

get_error_codes

HTTP method: GET

The get_error_codes operation returns an LLSD document describing the Reg API error codes. This information is reproduced in Registration API Error Codes. This operation does not take any parameters.

The errors are in an array, and each error is, in addition, contained in an array. The first element in the array is the error code, the second is the name of the error, the third is the description.

Example

The following HTML code illustrates a simple form to get the error codes: 

<form action="https://cap.secondlife.com/cap/0/UUID" method="GET">
   <input type='submit' value="Get Error Codes">
</form>

Example response: 

<llsd> 
   </array> 
       <array> 
           <integer>20</integer> 
           <string>missing required field</string> 
           <string>You are missing one of the required fields</string> 
       </array> 
... 
       <array> 
           <integer>1500</integer> 
           <string>malformed xml</string> 
           <string>Your xml is malformed</string> 
       </array> 
   </array> 
</llsd>

get_last_names

HTTP method: GET

The get_last_names operation retrieves the last names and corresponding IDs with which you are able to register new users.

Example

The following HTML code illustrates a simple form to get the valid last names: 

<form action="https://cap.secondlife.com/cap/0/UUID" method="GET">
   <input type="submit" value="Get Last Names">
</form>

Example response: 

<llsd> 
  <map> 
      <key>1926</key><string>Morellet</string> 
      <key>1683</key><string>Okamoto</string> 
      <key>1738</key><string>Rankin</string> 
... 
      <key>1870</key><string>Yang</string> 
  </map> 
</llsd>

get_reg_capabilities

HTTP method: POST

This operation returns the capability URL for each operation for which your account is authorized.

URI: https://cap.secondlife.com/get_reg_capabilities

POST parameters

  • first_name (Second Life first name)
  • last_name (Second Life surname)
  • password

For more information on capability URLs, see Using capability URLs.

DTD

This simplified version of the full LLSD DTD, enables stricter validation of result documents.

<xml><!DOCTYPE llsd [

<!ELEMENT llsd (map)> <!ELEMENT map ((key,(string|uri))*)> <!ELEMENT key (#PCDATA)> <!ELEMENT string (#PCDATA)> <!ELEMENT uri (#PCDATA)>

<!ATTLIST string xml:space (default|preserve) 'preserve'>

]></xml>
Retrieved from "https://wiki.secondlife.com/w/index.php?title=Linden_Lab_Official:Registration_API_Reference&oldid=637473"