`getuid` (Retrieve a user ID)

Retrieves an available user ID from a SAM pool.

Issuing getuid does not actually log in the requesting id.

Query string

The query string in the HTTP header contains the following parameters:

api

Specify the name of the API transaction.

apiversion

Specify the version of the API that should handle the requested transaction.

For the most up-to-date version, use apiversion=3.

uid

Specify a valid 1010data user name.

pswd

A valid password for the 1010data user name provided to the uid parameter.

gid

The group identifier for the SAM pool. In 1010data, a SAM pool is a group containing some number of UID's. A valid gid follows the same rules as a valid uid.

kill (optional)

Valid values for kill are as follows:

yes: Terminate the existing session and start a new one.
no: Do not terminate the existing session.
If no session exists, a new one will be created. If a session does exist, an error is returned.

Note: If kill=no and a session is active, the system returns an error.
possess: Log in and possess the existing session.
auth: Authenticate with the system but do not kill, possess, or start any session.

The default is yes.

Additional info

When using the getuid transaction, the user ID provided must be the owner of the group specified in the gid parameter of the query string, and the password provided must be the unencrypted password for that ID.

XML input to server

No XML input is required. All data for the transaction is specified in the connection string.

XML response from server

A successful result contains the following elements:

<rc>: The return code generated by the transaction. For a list of return codes, see Return codes.
<msg>: The message returned by the system. Specific messages correspond to specific return codes.
<uid>: The name of the user ID that is part of the specified group and currently not in use by another SAM pool process. This response is a string.

Query string example

https://www2.1010data.com/gw.k?api=getuid&apiversion=3&uid=$UID&pswd=$PSWD&gid=$GID

Valid `getuid` example

In the following example, clientx_admin is requesting a user ID from a group called clientx containing clientx_0 and clientx_1.

Request: 
https://www2.1010data.com/cgi-bin/gw?apiversion=3&api=getuid&uid=clientx_admin&pswd=*********&gid=clientx

Response(s):
<out>
<rc>1</rc>
<msg>OK</msg>
<uid>clientx_0</uid>
</out>

The getuid is successful and retrieves the user ID clientx_0.

You can now log in with the user ID clientx_0. You can possess the session, meaning that if the user is already logged in, you can retain the session cache.

Request: 
https://www2.1010data.com/cgi-bin/gw?apiversion=3api=login&uid=clientx_0&pswd=*********&kill=possess

Response:
<out>
<rc>0</rc>
<sid>1392666444</sid>
<pswd>Ha2mvx775hbl</pswd>
<msg>Last login was: 2019-09-10 21:44:26</msg>
</out>

Invalid `getuid` example

In the following example, clientx_admin is requesting a user ID from a group called clientx containing clientx_0 and clientx_1.

Request: 
https://www2.1010data.com/cgi-bin/gw?apiversion=3&api=getuid&uid=clientx_admin
    &pswd=*********&gid=clientx

Response(s):
<out>
<rc>1</rc>
<msg>You do not own the specified group.</msg>
</out>

However, this time, either the group clientx does not exist or clientx_admin is not the owner of the group.

getuid (Retrieve a user ID)