Private Records
A record in the "private" access group ("*" for short) can be read only by its uploader and by the users the uploader grants access to.
import com.skapi.*
import kotlinx.serialization.json.*
val skapi = Skapi("<Project ID>")
val rec = skapi.postRecord(
jsonOf("note" to "Only for me and my doctor"),
jsonOf("table" to jsonOf("name" to "health", "access_group" to "private")),
)
val recordId = rec["record_id"]!!.jsonPrimitive.contentimport com.skapi.java.SkapiJava;
import com.skapi.java.SkapiJson;
import java.util.Map;
SkapiJava skapi = new SkapiJava("<Project ID>");
Map<String, Object> rec = skapi.postRecord(
SkapiJson.obj("note", "Only for me and my doctor"),
SkapiJson.obj("table", SkapiJson.obj("name", "health", "access_group", "private"))
).get();
String recordId = (String) rec.get("record_id");To keep its data unreadable to the server as well, see Encrypting Private Data.
Anyone else who fetches it gets INVALID_REQUEST: User has no private access. The project owner and admins read a private record only on the same terms as any other user.
A private record that references another record can also be read by the users with private access to that other record: its uploader and the users it was shared with. See References.
Granting access
grantPrivateRecordAccess shares one record with up to 100 users at a time. Only the record's uploader can grant, unless the record was posted with "source" to jsonOf("allow_granted_to_grant_others" to true).
skapi.grantPrivateRecordAccess(recordId, listOf("<user id 1>", "<user id 2>"))skapi.grantPrivateRecordAccess(recordId, Arrays.asList("<user id 1>", "<user id 2>")).get();A granted user can read the record, even when it is private or above their own access group, and every record that references it. They can also reference it.
Removing access
skapi.removePrivateRecordAccess(recordId, listOf("<user id>"))skapi.removePrivateRecordAccess(recordId, Arrays.asList("<user id>")).get();The user cannot get a new private access key for the record after this. A key they already hold keeps working until it expires, so they lose access to the record and its files within 1 hour at most (see Private files).
Listing grants
listPrivateRecordAccess takes recordId, userIds, or both (at least one):
// who can read this record
skapi.listPrivateRecordAccess(recordId = recordId)
// which records this user was granted
skapi.listPrivateRecordAccess(userIds = listOf("<user id>"))// who can read this record
skapi.listPrivateRecordAccess(recordId).get();
// which records this user was granted
skapi.listPrivateRecordAccess(null, Arrays.asList("<user id>")).get();{"list": [{"record_id": "...", "user_id": "..."}, ...], "startKey": ..., "endOfList": true, ...}It takes the paging options as fetchOptions.
Moving in and out of private
Moving a record into or out of "private" removes every grant on it, in either direction. Grant again afterwards if those users should keep access. Only the record's uploader can move it across that line.
skapi.postRecord(jsonOf(
"record_id" to recordId,
"table" to jsonOf("name" to "health", "access_group" to "authorized"), // clears the grants
))skapi.postRecord(SkapiJson.obj(
"record_id", recordId,
"table", SkapiJson.obj("name", "health", "access_group", "authorized") // clears the grants
)).get();Private files
Files on a private record are private too. Their uploader and granted users read them with getFile and the other download methods as usual: skapi-kotlin asks the server for a private access key and adds it to the file request. The key is kept on the Skapi object and reused for that record.
A private access key is valid for 1 hour. skapi-kotlin renews it on its own: a key that has expired, or will within a minute, is replaced with a fresh one the next time it is needed.
requestPrivateRecordAccessKey is that request on its own. You only need it to build file requests yourself:
val key = skapi.requestPrivateRecordAccessKey(recordId)String key = skapi.requestPrivateRecordAccessKey(recordId).get();When your access comes from a record that the private record references, pass that record's ID as referenceId.
To hand a private file to someone without an account, make a signed link with expiresSeconds.
